Introduction

If you wish to know anything about the composite structure of an article or set of articles, it is not necessary to fetch the
entirety of every one of the relevant articles in order to harvest that small subset of desired information. For example, fetching 1000 complete articles simply to establish a site map involves the transfer of a good deal of redundant traffic. For this reason, Cortex provides an endpoint that allows you to pull in a summary of the articles' composite elements and implicitly exclude both the article content and any other fields that are not needed.

Most commonly, this facility is used to exclude the article content in order to reduce network traffic. For this reason, the
JSON response to a default article summary call is an array of articles with the article content removed. Below is an example of a summary for an individual article.

{"id": "a444de35-69a0-4b95-8a7c-69afcb8c1419",
 "clientId": "INCROWD",
 "version": 1 ,
 "slug": "slug text",
 "publishDate": null ,
 "pinned": false,
 "singlePage": false,
 "heroMedia": {
   "title": "Article Title",
   "content": {
     "id": "a26a6e8c-224f-4f9c-b926-55bef6c0cd97",
     "contentType": "IMAGE",
     "image": "https://imageLocation.com/imageidentity.bmp"
   }
 },
 "blocked": false,
 "lastModified": {
   "date": "2020-02-26T10:44:16.728Z"
 },
 "hasGeoBlocking": false
}

As you can see, all the composite elements are shown, but the actual content is removed.

Additionally, the call options allow for any of the featured fields to be included or excluded.

Use cases

You may have various reasons for wishing to fetch article summaries, however example use cases might be to create a
site map, or to build a front page for a website that comprises only the hero media for a number of articles and does not pull down all the content until the user clicks on a particular article.

Requirements

In order to fetch article summaries, the following request headers are required:

1. X-APP-ID
   Purpose: Identifies the application making the API request. Description: This header contains the unique identifier associated with the application initiating the API call. It helps the server recognise and authorise requests from specific applications.
2. X-API-KEY
   Purpose: Authenticates and authorises the API request. Description: This header carries the API key associated with the application, serving as a secure way to verify the identity of the requester and control access to the API resources. This is supplied by Cortex. Please contact your Cortex account manager to secure the API key.
3. X-REALM
   Purpose: Specifies the security realm for authentication. Description: The X-REALM header is used to indicate the security realm or domain within which the authentication process occurs. It provides additional context for the server to apply the appropriate authentication mechanisms.

Additionally, article summary API calls must be made from a server-side platform. The end-user or web browser should
not be fetching article summaries, as this may lead to security vulnerabilities and practical issues. For example, if creating a site map, web pages are rendered dynamically on the server-side, so building the site map from the browser will not necessarily create a site map that is representative of the site architecture.

The article summary API call

This section details the article summary API endpoint and field options.

The API construct to fetch article summaries looks like this:

💻

GET {environment-id}/v1/content?size={size}&page={page}&singlePage={singlePage}&tags={tags}&excludeTags={excludeTags}&categoryIds={categoryIds}&excludeCategoryIds={excludeCategoryIds}&fields={fields}

In which:

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://stage-article-cms.cortextech.io
• Production: https://article-cms.cortextech.io
• Production (US environment): https://article-cms.cortextech.us

{size} is an integer that determines the number of article summaries to be included in a single page of results. The value must be an integer with a maximum of 10,000. The default value is 1,000.
pageis an integer that indicates the specific page of results to be retrieved. Note that 0 is the first page, 1 is the second page, and so on. The default value is 0.

{singlePage} is a Boolean. If set to false it will return content that are not pages; that is, it will return articles, the general use case for which is anything shown with a timestamp in a rolling feed of content sorted by date and time of publication. Alternatively, if set to true this will return pages. These might include static content (such as the ‘Contact Us’ page), global components (such as the website footer) or configuration files (such as a list of redirects). The default value is false.

{tags} is a list of tags separated by commas, used to include content with the named tags. For instance, using tags=cricket,surrey returns summaries for content that include one or both of the tags "cricket" and "surrey".

{excludeTags} is a list of tags separated by commas, used to exclude content with the named tags. For instance, using excludeTags=news,football returns summaries for content which does not have the tags "news" or "football".

{categoryIds} is a list of category IDs separated by commas, used to specify the inclusion of content featuring one of the listed category IDs.

{excludeCategoryIds} is a list of category IDs separated by commas, used to specify the exclusion of content featuring one of the listed category IDs.

{fields} is a comma-delimited list of fields that are to be included or excluded in the response. In this way, this parameter allows you to fine-tune the content you receive by reducing the list of fields down to only those you wish to retrieve. For example, you can precisely specify the desired fields like this: fields=slug,publishDate. This means that the article summary will comprise only the slug and the publishDate. Alternatively, you may choose to exclude specific fields from the response using the fields parameter with a negative mask, like this: fields=-slug,-publishDate. In this case, the "-" sign before the fields indicates that the slug and publishDate fields should be excluded, effectively removing them from the data you receive and including all other fields in the article summary.

Note that you can also include or exclude fields within an object, for example, to fetch only the article slug and the title from within the content object looks like this: fields=slug,content:(title)

Example

For example, this call fetches a list of every slug and publishDate for all articles with the tag home and the category ID eddff78a-c41f-43d5-bc96-de2f515f985d.:

💻

GET https://article-cms.cortextech.io/v1/content?size=1000&page=0&singlePage=false&tags=home1&excludeTags=ad2&categoryIds=03b681f4-c137-4cf6-a24d- a4a2250f5dc1&fields=slug,publishDate