NEJM Catalyst Portal API

Definitions

  • Collection API - API that represents list of resources (i.e. a list of conferences)
  • Resource API - API that represents a single resource (i.e. a single conference)

API Authorization

API requests must contain a valid token, and be sent from an approved (white listed) IP address.

Token

All API requests must contain a valid token. The token is passed as a name/value pair in the query string.

GET /api/conferences/1?token=XXXX-XXXX-XXXX HTTP/1.1

From here forward, all API request examples in this documentation will omit the token query parameter for the sake of brevity.

API requests made with an invalid or missing token will result in a HTTP 401 response.

API Error Response Example - Missing or Invalid Token

HTTP/1.1 401 Unauthorized
{
    "error": "Unauthorized Token"
}

Approved IP Addresses

All API requests must be made from an approved (white listed) IP address.

API requests made with an invalid IP address will result in a HTTP 401 response.

API Error Response Example - Invalid IP Address

HTTP/1.1 401 Unauthorized
{
    "error": "Unauthorized IP"
}

Requesting Data

Filtering

All collection API's allow for filtering of the results on most of the resource's available fields.

Return all conferences with a status of "live" or "archive

GET /api/conferences?filters[state]=live,archive HTTP/1.1

Sorting

All collection API's allow for sorting on most of the resource's available fields.

Return conferences sorted by start_date, in ascending order

GET /api/conferences?orderBy=start_date&orderDir=asc HTTP/1.1

Specific fields

All resource & collection API's allow you to request the specific fields you want returned.

Return a conference with only the name, description & start_date fields

GET /api/conferences/1?fields=name,description,start_date HTTP/1.1

There are certain fields that will always be returned with every request. These include id and email for user resources. And for conferences, id, name and event_url.

Sub-resources

All resource & collection API's allow access to a predefined set of sub-resources. This allows you to request for those sub-resource relationships to be returned in the API response.

Return a conference with related sponsors & presenters.

GET /api/conferences/1?with=sponsors,presenters HTTP/1.1

Paginating

All collection API's allow for paginating of the results.

Return a paginated collection of conferences, with 5 results per page

GET /api/conferences?pageSize=5 HTTP/1.1

Note: In paginated results, additional links and meta keys will be delivered with the payload as follows:

{
    "data": [
        ...
    ],
    "links":{
        "first": "https://portal.com/api/conferences?page=1",
        "last": "https://portal.com/api/conferences?page=5",
        "prev": null,
        "next": "https://portal.com/api/conferences?page=2"
    },
    "meta":{
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "https://portal.com/api/conferences",
        "per_page": 5,
        "to": 5,
        "total": 23
    }
}

Creating & Updating

When sending a POST or PATCH request to the API, the request body needs to be formatted as valid JSON.

See Create User for examples.

Conferences API →