ACP or Amedia Content Platform is our service for accessing content from our 120+ publications. ACPComposer is the name of the service that provides the public API.
The ACP Composer API is versioned. This allows us to introduce breaking changes in a controlled manner. The version is given as part of the path for each request.
curl -i "https://services.api.no/api/acpcomposer/v1.1/..."
The current version of the ACP Composer API is .
For a given API version, we provide the following guarantees:
- API methods will not be removed
- Data attributes within a response object will not be removed
- The data format for attributes within a response object will not change
For a given API version, the following may occur without a version bump:
- New API methods can be introduced
- New attributes may be added to an object at any time
- Backward compatible bug fixes
An API version will be deprecated when a new version is introduced. Deprecated APIs will be kept alive for a minimum of 30 days.
Example
HTTP/1.1 200 OKWarning: 299 - "Deprecated API " "Thu, 01 Dec 2017 16:00:00 GMT"Date: Wed, 20 Jan 2016 10:25:49 GMT
We use the generic 299 code in combination with the text Deprecated API to indicate that the version is deprecated. If a date is provided, it will tell you when the version is removed. The message may provide information to aid in migrating away from the API.
All API access is over HTTPS, and accessed from https://services.api.no/api/acpcomposer. All data are sent and received as JSON, where we use the HAL format for Hypermedia.
The API is read-only. This means that it will only accept GET requests.
curl -i "https://services.api.no/api/acpcomposer/v1.1/resolve/http://www.ba.no"
HTTP/1.1 200 OKDate: Wed, 20 Jan 2016 10:25:49 GMTAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: Content-TypeCache-Control: must-revalidate, channel-maxage=120, group="/5-8", group="/5-8-1"X-Cache-Status: [ normal ; ]X-Trace-App: [ acpcomposer ; knata.api.kunder.linpro.no ; Wed, 20 Jan 2016 10:25:49 GMT ]Content-Type: application/json; charset=UTF-8; type=documentInfox-channel-maxage: 120x-hashtwo: /5-8 /5-8-1X-Varnish: 416160657Age: 0Via: 1.1 varnish-plus-v4X-Cache: MISSX-Trace-Cache: [varnish-general02-osl2.api.c.bitbit.net ; varnish-general02-osl2.api.c.bitbit.net ; Wed, 20 Jan 2016 10:25:49 GMT ; 120.000 orig-ttl]Content-Length: 382Connection: keep-aliveAccept-Ranges: bytes
Blank fields are omitted by default.
All timestamps are returned in the ISO 8601 format:
All responses will return the Content-Type application/json (Even though HAL recommends application/hal+json. In addition to that we add a type attribute in the header. This indicates the object type you will find inside the response. We use it to indicate the model object (This will be documented later).
Content-Type: application/json; charset=UTF-8; type=documentInfo
Some of our API methods accept additional, optional parameters. These parameters are passed as query parameters:
curl -i "https://services.api.no/api/acpcomposer/v1.1/search/content?publicationDomain=www.ba.no"
Resource IDs are specified as path parameters:
curl -i "https://services.api.no/api/acpcomposer/v1.1/content/5-35-224541"
In this example the resource id is 5-35-224542.
All content objects within the ACP Composer API are identified by its full URI. So the url https://services.api.no/api/acpcomposer/v1.1/content/5-35-83779 is said to be the unique ID of that object. This has the implications that a content object is only unique within the given domain and API version. There are no guarantees that it will be consistent between versions.
A Content-ID is a unique id for an object within the ACP Composer API. This is normally not something you need to worry about, unless you need to persist information about an object in your end.
Important information about Content-IDs:
- A Content-ID consist of characters, numbers, dot (.) or hyphen (-).
5-35-83779.1 is a valid Content-ID, while 5-35-83779!1 is not. - A Content-ID will always be part of the URI pointing to a content object within the ACP Composer API.Eg:
https://services.api.no/api/acpcomposer/v1.1/content/5-35-83779. - A Content-ID is guaranteed to be unique forever.
- A Content-ID might change for an object (!). If it is changed, you will be redirected to the content object with a new Content-ID.
WARNING:A Content-ID is build up by a number of internal IDs that are used to decipher information internally. Never try to be smart and construct Content-IDs based on know-how. Content-IDs must be used, not constructed!
The API is considered stable, but the the content is in constant change. Clients therefor assume that any request can result in a redirect.
Redirect responses are used in accordance with the HTTP 1.1. specification.
404 Not found We use this response code when a requested object wasn’t found. But also when a user doesn’t have access to the object.
Published, non-paywalled content is available through the API without any form of authentication. If accessing private or paywalled content is desired, an API key is required. If you think you require an API key, contact Amedia Support.
Once you have been issued a valid API key, authentication is done by adding the apikey header to your requests:
curl -H "apikey: <token>" "https://services.api.no/api/acpcomposer/v1.1/content/5-35-224541"
All responses from the API returns JSON in the HAL format . All _embedded objects are introduced to reduce the amount of requests required to retrieve a full content object. The _embedded objects can be only a partial representation of the object it represents. It is even allowed to divert from the original. The data in an embedded object can only be used within the context of the object it is embedded into.
The details of each API endpoint can be found here: