Skip to content

Content API

The Content API is used to create, modify or delete content (articles) in the Relevance platform. It can also be used to create, modify, delete and retrieve data associated with content, such as comments and likes.

What happens in the Content API

Content that is accepted by the Content API is processed before it is inserted in the platform:

  • content is scrubbed (potential malicious content tags are removed)
  • media items (images, videos, documents) are extracted from the content and optimized for use in the platform

Automatic media extraction only works for media items that can be accessed by our platform. This requires a public URL or (specifically configured) secure access.

If this is not possible in your situation or not preferred (e.g. because your organisation's systems can not be reached from the outside world) you can make use of our Cloud Storage solution. Media assets can be pushed to ORTEC's Cloud Storage before pushing content to this API. Fine-grained access control is available for our Cloud Storage solution.

Requirements

  • An ORTEC API key (contact your ORTEC service contact to obtain one)
  • The base url of your POST API instance

Authentication

All calls to the Content API must include a feed name and associated API key. These should be included as top-level attributes in any JSON data submitted to the Content API.

1
2
3
4
5
  {
    "feed": string,
    "apikey": string,
    [additional fields]
  }

For GET requests the feed and apikey should be included as query parameters.

Articles

Articles are created, updated and deleted by making an HTTP POST to /post

  • Content-type should be application/json
  • The post body should contain a JSON object

Article data

Article submitted to the Content API should have the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
  {
    "id": number,
    "action": "insert"|"update"|"delete",
    "cats": array of strings,
    "author": string,
    "title": string,
    "cdate": string,
    "mdate": string,
    "url": string,
    "content": string,
    "descr": string,
    "intro": string,
    "tags": array of strings,
    "shareurl": string,
    "meta": {}
  }
These fields are required in an article: id, title, cdate, url, content.

The content field may contain raw html.

Examples

Basic example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
  {
    "feed": "my-feed",
    "apikey": "api_key_received_from_ortec",
    "type": "our-feed-type",
    "articles": [
      {
        "id": "6d4230d0-a947-4202-8a9b-85697444052f",
        "action": "insert",
        "cats": ["News", "General"],
        "author": "G. Orwell",
        "title": "1984 - Chapter 1",
        "cdate": "2011-08-25T15:22:23Z",
        "mdate": "2011-08-25T15:22:23Z",
        "url": "https://1984.com/c-1",
        "content": "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, his chin nuzzled into his breast in an effort to ...",
        "tags": ["orwell", "big brother"]
      }
    ]
  }

Comments

Comments can be created, updated and deleted by making an HTTP POST request to /comments.

Comments can be retrieved by making an HTTP GET request to /comments.

Comment data

Comments submitted (and retrieved) from the Content API should have the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "externalID": string or number,
  "externalArticleID": string or number,
  "uid": string,
  "comment": string,
  "externalParentID": string or number,
  "cdate": date as ISO 8601 date string,
  "mdate": date as ISO 8610 date string,
  "ortecID": string,
  "status": boolean
}

All fields are mandatory unless otherwise indicated.

  • externalID: The ID of this comment in the external system submitting the comment.

  • externalArticleID: The ID of the article associated with this comment in the external system.

  • uid: The identifier of the user making the comment. This should be the same identifier as the one used in the Relevance platform.

  • comment: The comment text.

  • externalParentID (optional): The id of the parent of this comment in the external system.

  • cdate: The comment creation date.

  • mdate (optional): The modification date of the comment.

  • ortecID (optional): The ORTEC ID of this comment.

  • status: Whether the comment is active or not. Comments can be deleted by updating their status to the value false. Note that if a comment has children, deleting the comment will also delete all child comments.

Creating, updating and deleting comments

To create, update or delete a comment, make a POST request to /comments.

Request

The request should have the following structure:

1
2
3
4
5
6
{
  "feed": API_FEED_NAME,
  "apikey": API_KEY,
  "action": "insert"|"update",
  "comments": CommentData[]
}

See Authentication for a description of the feed and apikey fields.

  • action: The bulk action to be performed: insert or update. Submitting known comments with an insert will cause them to be updated. Submitting unknown comments as an update will cause them to be ignored.

  • comments: An array of comments, see Comment Data

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "feed": "{{content-feed-name}}",
  "apikey": "{{content-feed-apikey}}",
  "action": "insert",
  "comments": [
    {
      "externalId": 1,
      "externalArticleId": "ext_art",
      "uid": "user1",
      "comment": "This is a comment",
      "cdate": "2019-02-20T00:00:00Z",
      "status": true
    }
  ]
}

Response

The API will respond with an HTTP 200 code if the request is well-formed. In order to avoid timeouts with large submissions the API will not wait until all comments have been processed before responding.

If the request is malformed, the API will respond with an HTTP 400 code.

Fetching comments

To fetch comments, make a GET request to /comments.

Request

The request must contain the following query parameters (see Authentication) for a description of the feed and apikey parameters:

  • feed: The name of the feed.

  • apikey: The API key for the feed.

  • since: The date after which comments should be fetched. This date is exclusive. It should be a javascript timestamp (number of milliseconds since 1 January 1970 UTC).

  • action: One of insert, update or delete. This determines whether all inserted, updated or deleted comments are returned. A comment is considered inserted if its cdate is after the provided since date. A comment is considered updated if its cdate is before but its mdate is after the provided since date.

Sample Request

GET /comments?feed=afeed&apikey=AN1API2KEY&since=1550665608000&action=insert

Response

The reponse will contain the comments and the corresponding action. The structure of the comments will be as described in Comment Data, with the following differences:

  • externalID: This field will only be returned when it is known (it will be absent if the comment was first created on the Relevance platform and was never updated by the external system).

  • externalParentID: This field will only be returned when it is known (see externalID).

  • ortecID: This field will always be returned.

Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "action": "insert",
  "comments": [
    {
      "externalID": "1111",
      "externalArticleID": "ext_art",
      "uid": "user1",
      "comment": "This is a comment",
      "cdate": "2019-02-20T00:00:00Z",
      "mdate": "2019-02-20T00:00:00Z",
      "ortecID": "78737",
      "status": true
    },
    {
      "externalID": 2,
      "externalArticleID": "ext_art_2",
      "uid": "user2",
      "comment": "This is a comment",
      "cdate": "2019-02-20T00:00:00Z",
      "mdate": "2019-02-20T00:00:00Z",
      "ortecID": "93625",
      "status": true
    }
  ]
}