The absolute Minimum Knowledge required to understand the HAL-based API following the Example of the MediaCentral Asset Management CTC

The names of the properties of the other links are following a specific syntax: a prefix (e.g. "aa") followed by a suffix (e.g. "assets") separated with a colon resulting in "aa:assets". - Properties identifying link objects are called "link relations", or short "link rels", i.e. "aa:assets" is a link rel. . Another metaphor for link rels are "method names" or "method selectors", on which different HTTP verbs can be used and on which bodies of different Content-Type (sticking to the metaphor: the method arguments) could be used, we’ll discuss this later. The prefixes of the link rels are directly connected to the names of the CURIEs, listed in the property "curies", CURIE is for "compact URI expression". - What is the idea behind CURIEs?

Let’s inspect the CURIE "aa". The CURIE’s name "aa" acts as prefix for all link rels of a common subject if you will. Each CURIE is associated to a URI, specified in the CURIE’s href property, e.g. for "aa" we have "http://services.avid.com/api/assets/{rel}". The CURIE "aa" is also "templated", "templated" means, that we could fill the placeholder "{rel}" in the CURIE’s URI with a link rel’s suffix and get an expanded URL, e.g. for the link rel "aa:assets", we would get the expanded URL "http://services.avid.com/api/assets/assets". - The idea behind those expanded URL is to put an optional documentation of the link rel behind that URL, but in practice, this URL does not have an obligatory meaning, it should however be unique. In practice, and this is also a matter of lengthly discussions concerning HAL, a link rel should never change, i.e. the link rels "aa:assets" and another link rel "bb:assets" are considered different, even if their CURIEs' URIs are equivalent! - That means, that a CURIE does not directly specify a namespace identified by its URI, but it defines a prefix to give link rels a kind of structure. Just keep in mind, that CURIE URIs have no meaning at all, maybe they specify/name the vendor and refer to a documentation, but not more. There is no mechanism like XML-namespacing involved!

Rules for link rels:

Predefined names of the CURIEs:

I have a very simple rule for app developers: Ignore the presence of CURIEs mentally! They have no substantial meaning at all.

For the time being we only discussed the link rels to uniquely designate links. But what do those link rels virtually designate? The JSON-object right from the colon of a link rel property string under the "_links" property is called a link object. (The link rel "curies" does even have an array of link objects associated with it, as explained above, we could list the CURIEs for "aa", "pa" etc. in the "curies" array.) So, we have this general structure of links, link rels and link objects:

Let’s inspect the link object of the link rel "aa:assets":

Now let us just follow the link rel’s "aa:assets" href "http://upstream:8080/apis/avid.mam.assets.access;version=0;realm=SYSTEMID/assets".

We’ll get this response:

What do we see here:

Let’s continue using the HAL response we got from requesting "aa:assets". - The whole HAL-based JSON object is a so called "resource" in HAL lingo. So, the very first request we did to get the service root, responded with the service root resource! Then we started from this resource, following the links to get other resources. The term resource is actually a REST term, and the returned HAL-based JSON object is in reality a "representation of an underlying resource", but HAL uses the term "resource" interchangeably with "representation of the resource".

The aa:assets resource is a collection, meaning that it represents all of the assets in the associated system. The link relations in this resource correspond to operations that apply effectively to the whole asset data store, including creating, retrieving and deleting individual assets.

Link Rels and Resources: A link rel is a key to a certain link object. A link object contains an href with a URL, that acts as a pointer to a certain resource. Abbreviated: link rels point to resources.

Using the REST-based API means following the links given in a resource at hand. In the case of the resource "aa:assets" we’ll select the link rel "aa:asset-by-id". We want to follow the href in "aa:asset-by-id"'s link object, therefore we have to:

All right, in order to expand the URI template in the href, i.e. "http://upstream:8080/apis/avid.mam.assets.access;version=0;realm=SYSTEMID/assets/{id}", we have to know something about the semantics of the link, and what the link, i.e. the HTTP request, will return. In this case, yes I know that from the APIs documentation, I have to replace "{id}" by the id of the asset I want to retrieve. Assuming, that the id is "12374176-1c8d-42b3-9d10-7cf19b0f3fb2", the constructed expanded URL would be "http://upstream:8080/apis/avid.mam.assets.access;version=0;realm=SYSTEMID/assets/12374176-1c8d-42b3-9d10-7cf19b0f3fb2". Having that completed URL, we can issue another HTTP GET request, to retrieve the resource of that asset. To have that request work, we have to pass the access token again in the header field "Authorization". E.g. via wget from the command line:

The HTTP response of that GET request carries another resource in its body: the asset resource. Let’s inspect it!

Reconsidering the structure of the response of calling "aa:assets", we’ll notice, that this response also is a resource! - Of course it is, because HAL-based APIs only use resources as substantial means of communication. The structure of the "aa:assets" resource and the structure of the "aa:asset" resource only have the "_links" property and esp. the "curies" and "self" properties thereof in common (the hrefs of both "self" link objects do of course differ, because they are different resources). To drive this point home: JSON objects, representing HAL resources can contain links (property "_links") as well as a bunch of arbitrary other properties on the "top level". - In this case the "aa:asset"-resources properties denote more meta information about the individual asset we’ve queried. The properties of a resource are case-sensitive following JSON/JavaScript rules, the casing of the properties might be camelcase or hyphenation (Lisp-case).

We followed the link rel "aa:asset-by-id" to get this resource. In HAL, the original link rel that lead to this resource is implicitly also the type of the resource if you will. In the case of "aa:asset-by-id", this would mean that the resource in the response is an "aa:asset-by-id"-resource, but for matters of clarity, we consider this being an "aa:asset"-resource actually. - As we already discussed, the self link refers to the URL, which was expanded from the original link rels URI template. So the original URL or self link is basically location of that specific resource.

However, we should discuss the link rels in the property "_links" we have in this resource:

Like every HAL resource we have the property "_links", which we have just discussed, esp. the link rels and link objects. But this time we have more "top-level" properties in that resource (compared to the "aa:assets" resource).

From the standpoint of purity, clients should never apply/rely on hard coded ("bookmarked") URLs and they should never build URLs manually, but instead follow link rels every time, e.g. from the root resource to the elementary resource in question. Sure, this puts a greater burden on clients, but this is basically the way hypermedia should work. However, in order to have more efficiency a caching strategy might be appropriate.:

When it comes to retrieving the entry point of a service, is that something that I as a consumer of that and possibly other services should be cashing or would I retrieve the entry point every time I need to interact with the service again? If cashing is ok, what is a good granularity of expiring that information?

We just mentioned the concept of embedded resources, which is also a genuine concept of HAL. Therefor some of the links, e.g. "aa:asset-by-id", do also support to specify child resources, which should be embedded in the returned resource. - As already discussed, links, which allow specification of embedded resources are not marked in a special way, instead some known semantics/prior knowledge (hopefully documented) is required.

The idea of embedding is of course interesting to save us from many web requests and getting stuff in bulk instead. Mind that the size of messages are limited on the bus! Let’s Inspect a resource containing an embedded resource by requesting this:

The returned response looks like this (some parts have been elided for brevity):

Let’s dissect this HAL resource from the JSON’s root. We have the top-level properties "base", "common" and "_links" as always, also mind, that "_links" contains the link rel "curies" among others.

The new property is named "_embedded", as the reader may have noticed, those properties with the "_"-prefix have a predefined meaning in HAL. Within "_embedded" we find the embedded resource as response of the issued request. It is not required to explain the details here, because the structure of the resource is basically equivalent to the stuff we have already discussed, and it also depends on semantics, which have to documented somewhere. However, there is one important point: curies will only be defined in the very top-level resource, e.g. for the embedded resource object of "type" "ma:asset-attributes-axf" the CURIE "ma" is defined on the top-level resource. - It means, that for link rel discovery, it is required to analyze the top-level resource for CURIEs, not the embedded one.

Mind, that embedded resources do also have self links, this is required because we have to be able to associate hrefs to those resources, because we don’t know their origin based on the original request-URL of the "surrounding" resource.

For completeness, it should be mentioned that the JSON-object right from the colon of a link rel property string under the "_embedded" property is called resource object. So, we have this general structure of embedded resources, link rels and resource objects:

Esp. requesting the service root resource, "http://upstream:8080/apis/avid.mam.assets.access;version=0;realm=SYSTEMID/", does always embed the resources "aa:assets", "loc:locations" and "search:searches":

In other words, one could either follow the link rel "aa:assets" from the service root in order to get further links for, e.g. the link rel "aa:asset-by-id", or one could directly follow the link rel "aa:asset-by-id" on the embedded "aa:assets" resource. As can be seen the CURIEs for the embedded resources are all defined on the very top level resource, as shown in the example having "ma:asset-attributes-axf" embedded before.

When dealing with HAL resources, you occasionally stumble over a dilemma: On the one hand, a HAL resource should be complete in the sense that it contains all information that is useful for a client. On the other hand, some pieces of information are probably not supported by all systems or are very expensive to get.

To deal with that, some properties in this documentation are marked as optional. This means:

Of course, that puts the burden on the client. It must implement logic to deal with optional properties. To simplify that we declare some properties as optional, but requestable in this documentation. Optional, but requestable properties can be requested with the query parameter insist. This means:

This is typically used for properties that are expensive to get. An example is the property totalNumber when returning a defined range out of a large list of items, e.g. when returning one page of the results of a search, or when returning one page of items in a folder. For a client, the total number is useful to show a UI control for paging. But it can be very expensive to get the total number of items. It can, for example, require additional database queries. So, the performance would suffer if the property is returned all the time, even though a lot of clients won’t need that number at all.

!!Notice, that HAL-based JSON can not be converted into XML directly. The problem is that HAL uses JSON-properties having colons in their names like "aa:attributes". - Such a property name can not be used as name for an XML element or attribute, because colon is used as separator for namespace-qualified names in XML!!

Up to now, the basic communication protocol we use for the REST-based connectivity toolkit is HTTP and we kind of "re-purposed" HTTP verbs as well as resources to act as means to transport our API calls and data. The same is true for error cases. Our REST-based API also makes use of HTTP error codes to signal error cases to the caller. The Content-Type of an error-response can have the value "application/vnd.avid.problem+json" to signal, that it is an SDK-related error, rather than other "infrastructure" issue. - When the Content-Type is "application/vnd.avid.problem+json", a description/message of the error is awaited in the response body. This text will not go into all the gory details of existing HTTP error codes, and how those should be applied in a clean REST interface. Instead the general idea will be shown. The details about error codes, which may be issued by API calls is documented in the API documentation in detailed manner.

It should be said, that callers of REST APIs should always be aware of the mentioned "infrastructure" issue, which have nothing to do with the requested service per se. Especially timeouts or unreachable endpoints could happen at any time during the application of REST and HATEOAS.