Public API

Introduction

This document tells you how to get posts/bulletins from the public endpoints in the Live Center API. It is intended for developers who want to include API calls in their own products or services, such as mobile apps, publishing platforms etc.

Client-side parsing of Bulletin/Post objects and their embeds such as video, images, tweets etc are not in scope for this document.  This document deals with getting the data and maintaining a feed.

What you should have before you start

  1. Experience in polling public APIs using AJAX or CURL
  2. The necessary documentation to be able to parse the JSON that you receive within the posts. 

What you should know after reading this

Before you start coding be sure that you are confident that you understand that :

  1. This guide tells you how to poll the API over https. Pushing from server to clients is possible using websockets. You may also use JSON-P if you want, see JSON-P.
  2. Keep in mind that bulletin and post is the same thing. It is called Bulletin at the serverside and therefore also in API routes, but generally referred to a “a post” clientside.
  3. When to use Latest, Earlier and other api calls, and when to use a combination of Initial/Changes cycle.
  4. What cutoff is and how it is affected by forward
  5. What the Success/Result json wrapper is
  6. What the Changes object is and its purpose.
  7. What the Channel Content object is and its purpose
  8. The caching model and how CDNs treat URLs 

Concepts

The initial / changes cycle

To connect to a feed, we typically use a combination of calls to Initial and Changes. This illustration shows the recommended setup using AJAX calls to API endpoints.

Bulletin / Post

A bulletin or a post is a short news article written into a channel in the Live Center. It has an id, title, author and may contain links to other resources. The Bulletin object is enclosed in a success/result wrapper. Each bulletin post is a JSON object. The specifications for this JSON object depends on the plugins in use, a nd is not in scope for this document.


BulletinFeeds

A bulletinFeed takes the ChannelId as an argument. Therefore, it can hit the database. Usually, each newspaper has one channel setup to be a stream, and it can set up new feeds on demand. Additional streams that leverage caching can be set up if required.

TenantKey

A tenantKey is a unique key that identifies your organization’s channels. It is added as a part of the request URLs to the Live Center API. In addition to identifying your organization, it also is a performant way of handling CDN requests as opposed to request parameters.

ChannelContent

ChannelContent is information that pertains to the entire feed. This is information about the channels name, countdowns, channel-extensions etc. The client should then just overwrite the channelContent whenever it receives it, and handle updates for countdowns etc.

Initial / Changes route

A strategy for starting an updated stream where you begin with an Initial query and continue to poll for Changes using the lastChangeId received in the initial.

A subsequent call to Changes gives you another lastChangeId which is used on the next call.

Latest route

A single stateless query that returns that last 20 posts that were created in that channel.

Earlier route

Used by the “show more” button. Earlier returns the 20 last ids that were created or modified before (but not including) a certain id, called the “cutoffId”.

Success/Result wrapper

Looks like this { success: true, result: … } and encloses all API responses. Always assert that success = true. Makes it easier to check if the server understood your API call or not.

AddedOrChanged Object

Common to the Initial and Changes response is the addedOrChanged object.

In the example below, the addedOrChanged contains one new bulletin/post and one updated bulletin/post since the provided cutoffId. The client should insert the new post and update the existing post.

Notice the lastChangedId variable. This can be used in the next call. Successive changes objects that are updated and appended produce the same result as polling for “latest”, but uses a fraction of the processing power and bandwidth.

CDNs and query parameters

Some CDNs and proxies handle requests with query parameters differently than with those without query parameters. Most API routes therefore avoid having query parameters.


Routes

Bulletin Feed Routes

Initial (to start a listening cycle)

/BulletinFeed/{tenantKey}/{channelId}/Initial

Returns the latest version of the 10 posts that were created last. The initial also returns a lastChangeId indicating the state of the server when it provided you with the initial call.

Returns :

  1. ChannelContent
    Information pertaining to the entire channel
  2. AddedOrChanged
    Contains the latest version of the last 10 Bulletins/Posts that was Created. Named addedOrChanged to keep it similar to the changes object.
  3. LastChangeId
    Use this as a parameter for the first subsequent call to the BulletinFeed/{channelId}/Changes endpoint.

Example:

https://livecenterdemo-test.azurewebsites.net/BulletinFeed/example_tenant/77/Initial

Changes (to poll for changes)

/BulletinFeed/{tenantKey}/{channelId}/Changes/{lastChangesId}

Returns all changes that have occured to posts since the time and state identified by the server using the lastChangesId parameter.

Parameters

●     ChannelId (Required)
The id of the channel you are polling

●     LastChangeId (Required)
A number representing a state. The server will provide what has changed since this point in time.

Returns

●     ChannelContent
Information pertaining to the entire channel. Overwrites previous version if set.

●     AddedOrChanged
Contains the latest version of the last Bulletins/Posts that was either Created or updated since the time and state given to the server through the LastChangeId.

●     LastChangeId
An unique Id identifying the state of the server when it returned this result. Use this for the next Changes Call.

Calls to Changes might be rejected. In these cases it will return an initial within the result wrapper Initial. The client should handle a response from Changes in such a way that an when rejected = true, the initial object is handled accepted.

Rejected response Accepted response
{ success: true, result: {

ts: 1492779075,

rejected: true,

initial:

{...}

}}

{s uccess: true, result: {

ts: 1492779282,

lastChangesId: 16254,

addedOrChanged:

[...]

}}


Latest

/BulletinFeed/{tenantKey}/{channelId}/Latest

Returns the latest version of the 20 posts that were created last.

Parameters

●     ChannelId (Required)

Returns

●     Success

●     Result (array)

Earlier - (Show more)

/BulletinFeed/{tenantKey}/{channelId}/Earlier/{cutoffId}

Earlier is the call used by  “Show more” button or similar. It returns the 20 bulletins/posts that were created immediately prior to the id passed as “cutoffId”. In order to get 20 more posts, pass in the id of the oldest post that you have.

Return the latest version 20 bulletins/posts created prior to the bulletin with id 17343

Parameters

●     ChannelId (required)

●     CutoffId (required)

Returns

●     Success

●     Result (array)
An array of up to 20 Bulletins/Posts created immediately prior to the post given by the cutoffId

Example :

https://livecenterdemo-test.azurewebsites.net/BulletinFeed/example_tenant/77/Earlier/2374


Get a specific bulletin by ID

/Bulletin/{tenantKey}/{bulletinId}/{channelId}

Parameters

●     BulletinId

Returns

The latest version of a bulletin/post.

Example :

https://livecenterdemo-test.azurewebsites.net/Bulletin/example_tenant/2374/77/

Bulletin edit history

/Bulletin/{tenantKey}/{BulletinId}/History

Parameters

●     BulletinId

Returns :

The edit history of the post.

Example:

https://livecenterdemo-test.azurewebsites.net/Bulletin/example_tenant/2374/History

Get bulletins

/BulletinLookup/{tenantKey}?channelId={channelId}&count={count}&cutoffId={bulletinId}

Query parameters :

●     channelId (required),

●     cutoffId (required),

●     count (optional)

●     quantKey
Accepts comma separated values for.Example :&quantKey=S57,S59&...

●     forward
Bool, accepts true, false. Default is false. Passing 1 and 0 will cast the value to bool.

●     Tag
Accepts one tag.

Returns

A list of bulletins/posts if available. The cutoffId is used to specify a point in which a search begins. The search is by default backwards, limited by the count. However, in some case you want to scan forward from the cutoff. For this there is the forward=true option.

In addition to changing the sort order to ascending, the forward option also changes on which side of the cutoff the selection is made.  The behaviour of the cutoff and the forward keyword is very practical for the navigation between pages of a resultset, but it can be a little counter-intuitive at first. See illustration on next page for clarification.

Example

https://livecenterdemo-test.azurewebsites.net/BulletinLookup/example_tenant?channelId=77&count=20&cutoffId=2385

https://livecenterdemo-test.azurewebsites.net/BulletinLookup/example_tenant?channelId=77&count=20&cutoffId=2385&forward=true


Bulletin Search

/BulletinSearch/{tenantKey}?channelId={{channelId}}&count={{count}}&query={queryString}

Returns posts that contain a case insensitive match for the query string anywhere in either the content body or the title. Will improve performance by indexing serverside when a use case that needs this. Contact Norkon if you have such a use case.

Rest Parameters: None

Query parameters :

●     channelId (required),

●     Query (required)

●     count (optional)

Returns

A list of results sorted in the order of

Example

https://livecenterdemo-test.azurewebsites.net/BulletinSearch/example_tenant?channelId=77&count=10&query=content

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? How can we help? How can we help?