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.

  {
    "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:

  {
    "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:

  {
    "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:

{
  "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
}

When submitting a comment, all fields are mandatory unless indicated otherwise.

  • 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 (optional for updates): 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 (not necessary for updates): The comment creation date.

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

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

  • ortecParentID (optional) : The ORTEC ID of the parent of this comment. This field can be returned when fetching comments. This field can be used when submitting comments to add a child to a comment created on the ORTEC platform.

  • 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:

{
  "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 as inserts will cause the request to fail. A comment can be deleted by updating its status to false.

  • comments: An array of comments, see Comment Data

Sample Request

{
  "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 (or deleted) 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, sorted reverse chronologically (from newest to oldest) by cdate. The response will not contain comments that were last modified (inserted, updated or deleted) by the external system.

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 ORTEC platform and was never updated by the external system).

  • externalParentID: This field will not be returned.

  • ortecID: This field will always be returned.

When fetching deleted comments, only a minimum set of fields will be returned: externalID, ortecID, cdate, mdate, status and externalArticleID.

Sample Response

{
  "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
    }
  ]
}

Likes

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

Likes can be retrieved by making an HTTP GET request to /likes.

Like data

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

{
  "externalID": string or number,
  "externalArticleID": string or number, 
  "uid": string,
  "cdate": date as ISO 8601 date string,
  "mdate": date as ISO 8601 date string,
  "ortecID": string,
  "status": boolean,
  "data": freeform JSON object
}

When submitting likes, all fields are mandatory unless indicated otherwise.

  • externalID: The ID of this like in the external system submitting the like.
  • externalArticleID: The ID of the article associated with this like in the external system.
  • uid: The identifier of the user liking the article.
  • cdate: The date the like was made.
  • mdate (optional): The date the like was modified.
  • ortecID (optional): The ORTEC ID of this like.
  • status: Whether the like is active or not. To delete a like set the status to false.
  • data (optional): Extra data associated with the like. This allows a like to express a general reaction rather than just a like. This can be achieved by associating an emoji with a like for instance.

Creating, updating and deleting likes

To create, update or delete a like, make a POST request to /likes.

Request

The request should have the following structure:

{
  "feed": API_FEED_NAME,
  "apikey": API_KEY,
  "action": "insert"|"update",
  "likes": LikeData[]
}

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

  • action: The bulk action to be performed: insert or update. Submitting known likes as inserts will cause the request to fail. A like can be deleted by updating its status to false.

  • likes: An array of likes, see Like Data

Sample Request

{
  "feed": "{{content-feed-name}}",
  "apikey": "{{content-feed-apikey}}",
  "action": "insert",
  "likes": [
    {
      "externalID": 1,
      "externalArticleID": "ext_art",
      "uid": "user1",
      "cdate": "2019-02-20T00:00:00Z",
      "status": true,
      "data": {
        "emoji": "U+1F60B"
      }
    }
  ]
}

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 likes have been processed before responding.

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

Fetching likes

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

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 likes 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 likes are returned. A like is considered inserted if its cdate is after the provided since date. A like is considered updated (or deleted) if its cdate is before but its mdate is after the provided since date.

Sample Request

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

Response

The reponse will contain the likes and the corresponding action, sorted reverse chronologically (from newest to oldest) by cdate. The response will not contain likes that were last modified (inserted, updated or deleted) by the external system.

The structure of the likes will be as described in Like 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 ORTEC platform and was never updated by the external system).

  • ortecID: This field will always be returned.

  • data: Likes made on the ORTEC platform will not have any associated data.

When fetching deleted likes, only a minimum set of fields will be returned: externalID, ortecID, cdate, mdate, status and externalArticleID.

Sample Response

{
  "action": "insert",
  "likes": [
    {
      "externalID": "1111",
      "externalArticleID": "ext_art",
      "uid": "user1",
      "cdate": "2019-02-20T00:00:00Z",
      "mdate": "2019-02-20T00:00:00Z",
      "ortecID": "78737",
      "status": true
    },
    {
      "externalID": 2,
      "externalArticleID": "ext_art_2",
      "uid": "user2",
      "cdate": "2019-02-20T00:00:00Z",
      "mdate": "2019-02-20T00:00:00Z",
      "ortecID": "93625",
      "status": true
    }
  ]
}