Representations
The API can return following type of representation :
- HAL+JSON for resource representations
- Markdown for documentation
- JSON for Swagger 1.2 description
Media-type and version
The HAL+JSON media-type contains also the API version and encoding format.
Default behavior of the API is to return a representation of the resource in the latest available API version. Current version is 1.
Client application can specify expected representation using Accept HTTP header.
/!\ API version is different from Keepeek release life-cycle. On each new API version resources representations will not be backward compatible with previous one.
HAL
HAL is a specification over JSON. HAL+JSON documents defines _links and _embedded properties. With these properties, Keepeek API returns resources and transitions related to the requested resource, referenced as Hypermedia in litterature.
- _links : this object contains links related to the resource grouped by relation type (IANA registered and Keepeek specific ones)
- _embedded : this object contains collection of embedded representation of linked resource. For example in a collection resource, embedded object can expose a subset of properties for each item.
GET http://baobab.keepeek.com/api HTTP/1.1
[...]
HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1;charset=UTF-8
{
"version": 1,
"release": "3.7.9",
"_links": {
"self": {"href": "http://baobab.keepeek.com/api"},
"curies": [ {
"name": "kpk",
"href": "http://baobab.keepeek.com/api/doc/rels/{rel}",
"templated": true
}],
"kpk:dam": {"href": "http://baobab.keepeek.com/api/dam"},
"help": {"href": "http://baobab.keepeek.com/api/doc"}
}
}
See hal spec for more details on HAL representation