ACP or Amedia Content Platform is our service for accessing all the content that our more than 70 publications creates. ACPComposer is the name of the service that provides the public API. In this documentation we use these names randomly, but it will all be reffering to the API.
Versioning
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/..."
New versions of the API will be announced on our blog.
Current version
The current version of the ACP Composer API is v1.1.
Guarantees
Within one version of our API we guarantee that:
API methods will not be removed
Data attributes within a response object will not be removed.
The data format on an attribute will be consistent
But this is also true for a version:
New API methods can be introduced
New attributes can be added to an object at any time.
Bugs will be fixed and announced on our blog.
Deprecation
A version will be deprecated when a new version is introduced. We will remove a deprecated version as soon as possible, but try to keep it alive for at least a month.
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.
Schema
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:
Headers and Content Types
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
Parameters
Some of our API methods takes extra or optional parameters. These parameters are passed on as query parameters.
curl -i "https://services.api.no/api/acpcomposer/v1.1/search/content?publicationDomain=www.ba.no"
Object id’s (The part of a url that points to a specific object in the API) are always given as part of the query string.
curl -i "https://services.api.no/api/acpcomposer/v1.1/content/5-35-224541"
In this example the object id is 5-35-224542.
Root Endpoint
You can issue a GET request to the root endpoint to get an overview of the current active versions. Our goal is to make the API fully traversable, but we are not there yet.
curl -i "https://services.api.no/api/acpcomposer/"
Unique IDs
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.
Content-IDs
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!
HTTP Redirects
The API is considered stable, but the the content is in constant change. Clients must therefor assume that any request can result in a redirect.
Redirect responses are used in accordance with the HTTP 1.1. specification.
HTTP Errors
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.
Authentication
Open content are available through the api without any form of authentication, But unpublished content and content behind our paywall can only be obtained if a valid api key is send with each request. What the key gives access to is controlled in our end. Contact us to receive a valid key.
Added the key to each request is done by adding a HTTP Request Header.
Authentication sent in a Headers
curl -H "apikey: token" "https://services.api.no/api/acpcomposer/v1.1/content/5-35-224541"
Where token is the key received from Amedia Utvikling upon request.
Hypermedia
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.
Endpoints
The details of each API endpoint can be found here: