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": {}
}
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
orupdate
. Submitting known comments as inserts will cause the request to fail. A comment can be deleted by updating its status tofalse
. -
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
ordelete
. This determines whether all inserted, updated or deleted comments are returned. A comment is considered inserted if itscdate
is after the providedsince
date. A comment is considered updated (or deleted) if itscdate
is before but itsmdate
is after the providedsince
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
orupdate
. Submitting known likes as inserts will cause the request to fail. A like can be deleted by updating its status tofalse
. -
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
ordelete
. This determines whether all inserted, updated or deleted likes are returned. A like is considered inserted if itscdate
is after the providedsince
date. A like is considered updated (or deleted) if itscdate
is before but itsmdate
is after the providedsince
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
}
]
}