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