HyperMedia
Summary
MediaValet has produced a Hypermedia API. Each object returns has a list of actions, or functions that are available to the object. These actions are based on the type of object, its state, and most importantly: the permissions of the authenticated user.
All functions are described in the JSON-Home document. Each function the authenticated user has access too is listed in the JSON Home document. There is also other data in there, such as: allowable verbs, link to help, link to the relations document, authorization scheme, and the status of the link. For more information, see the JSON-Home section.
JSON-Home
The JSON-Home document describes all the resources, or functions, available to the authenticated user. In each record is a list of the verbs available, and what authorization is required to call the end-point.
The document is based off of the IETF Standard for JSON-Home. There are some minor modifications that we uses:
- We use resource names as the key for each record
- The Relations Document is located as a field in the record
- Currently we do not list Relations Document for variables
- Currently we do not list accepted content type for each verb
- We have added a templated field to indicate the item is templated.
We do want to modify the document to follow the standards, and will be working towards that goal.
Our JSON-Home document looks like this:
{
"functions": {
"someFunction": {
"rel": "https://developer-california.mediavalet.net/rels/assets#asset_details",
"href": "/someFunction",
"templated": false,
"hints": {
"allow": [ "GET", "POST" ],
"formats": [ "application/json", "application/xml" ],
"docs": "https://developer-california.mediavalet.net/someFunction",
"status": "Active",
"auth-req": {
"scheme": "Bearer"
}
}
}
Description on the fields in the document:
- someFunction is the name of the resource. This is the value that shows up in the objects _links section.
- rel is the uri of the Relations Document for the end-point.
- href is the relative url to the end-point. This value should be added to the dns name of the server.
- templated is true if there are variables in the href field.
- hints contains helpful information for calling the resource.
- allow is a list of HttpVerbs that are accepted for this resource.
- formats is a list of content-types that are returned from this end-point.
- docs is the human readable documentation for this resource.
- status indicates the current status of the resource (Active, Deprecated, Deleted)
- auth-req lists all available authentication methods for the resource.
Links
Link (_links) is a section that is appended to each object that is returned from the API. It is a string list of resources that are available to process the object. The resource should be matched to an entry in the JSON-Home document to create the call into the API.
MediaValet suggests a system where the _link item is combined with the verbs in the allow section of the entry in JSON-Home to create easy to remember names. i.e. taking categoryAssets + POST = addCategoryAssets.
{
"id": "4ac3cd6c-e1ce-4dba-ae78-56b0a2f26bd9",
"name": "TestCategory",
"_links": {
"functions": [
"categories",
"subCategories",
"categoryAssets",
],
"self": "category"
}
}
Additional Reading
For further information on hypermedia and JSON-Home, please see the following