No rest 4 REST - introduction and #1

The API Managers or Enterprise Architects in charge of improving web services exposition, are facing thousands of REST API design or (swagger) validations and would like to be fully RESTful compliant and truthful to the original and still valid Roy Fielding’s spirit, twenty years later. Thus, several elements are necessary to be arbitrated, promoted to all stakeholders of these projects, well-accepted in the best conditions, but mostly understood for the benefits of the entire enterprise (with both the usual meanings of company and organization).

API Management and exposition are not only a pure technical act. Clearly very often the swagger is presented with a poor quality and almost in a complete standalone mode against the necessity to have an organization spirit, transverse to domains and with shared, accepted, and unique semantic standards.

In companies sensitive to these facts, API guidelines are written, administrated, maintained, and shared internally, with partners and even the public (OPEN APIs). That is the case of the renowned Zalando API’s guidelines, the ones of airways companies (vital to sell seats by all online travel metasearch engines) or banks. Having these rules is necessary to accelerate and promote its API to fully enter the Digital Age.

These articles "#X" will not only be for techies but for architects and even data manager as well and will focus on interpreting and trying to fix usual RESTful approaches or now current practices but which are remaining moments of tension in a collaborative spirit. Few examples:

- Is it indeed forbidden to put more than three chained concepts/resources in a resource path?

- Are only conceptual resources coming from a modelling metamodel allowed in a resource path?

- How to delete a set of instances with a significant size by a minimum of “call”?

- Must unlinking elements not be made by a DELETE but with a PUT or a PATCH instead?

- …

The resource path is the string dedicated to describing the access to the resource in the URN (before the “?” that is introducing the query param’s string, for a verb GET only).

Please note that conventionally, in this article, we will use the term resource both for the referring resources (including the conceptual one) and all the instances of its resources. Resource is a quite large notion for Fielding but some resources are veritable concepts that can be modelled in a metamodel (an employee, a warehouse, a container, …) and, indeed, resources can be the contextual ones (a recommendation of relevant courses for a student, the set of documents required for a bank loan, …).

In several articles we will deal with advanced but real use cases usually known by API managers. Moreover, subjects to be tackled and not yet stated solutions which are remaining to be handled by your company needs to be arbitrated. Let us try to progress together... with a first short use case!

#1 - Is it a resource or a facet of a resource then could I put it in my resource path?

Let’s take an example. Is the object “Price” a concept-resource for your company allowed to be put in the URN’s resource path?

Fielding defines resources (chapter 5 of its thesis) such as “any information that can be named can be a resource” and also “any concept that might be the target of an author's hypertext reference”. A resource path is not obviously and mainly the resource itself, but it is a kind of a track to obtain / reach the resource. Fielding is using the term "concept" for more static elements. With a so open definition, the number of paths can rocket and be very heterogeneous. In a large company with thousands of resources it will not be satisfying to operate with.

Then, it is why we prefer to transform the usual term of a resource in a large company into an alias of the conceptual resources … The content of a resource path will be a set of known objects and only concept-resources linked with its contextual representation for the call and result. Fielding’s evokes it by “abstract definition of a resource” that “allows an author to reference the concept rather than some singular representation of that concept”. Hence, as these ambiguities are removed, we are free to fix them.

A facet (example of a term to be used both in the payload and the query param area) will be a homogeneous set of properties of the resource (again, only a concept-resource). With this fitting and understood term it will be the best manner to assimilated it as a contextual resource.

The basic question could be “Can I create an object’s price completely separated from known resources (products, services)? If so, it is a concept-resource if not, it will be a usable resource to be put in the resource path. This case will be difficult to handle for a lot of people if it is not included in the guidelines and sustainable arbitrated, once an accession is obtained …

If a price is always adjacent to a product in a repository of the Master Data Management tool, which is a usual situation, it would be difficult to make it as a major root/parent object: price of what? of products, services, of nothing in particular? No … it will be only a set of properties in a more wider repository, even if its name can be ‘Referential of Prices” (the product or service is implicit and a key entrance to find this set of attributes could be made of a currency, an amount, a validation or dates of effectiveness, etc.).

Then, it will be forbidden to call it and to assimilate it to a "resource". It will not be a metaobject in the metamodel but instead, a property or a set of attributes on the concept-resource in the metamodel.

For a GET it will be a kind of filter or facet in the query param, for a POST/PUT/PATCH, it will be set in the body payload. A price will be impossible to be removed by a DELETE … it will be only changed or put to “Null” in the concept-resource attached.

GET …/after_sales/services/{id}?facet=prices but not GET …/after_sales/services/{id}/prices anymore.

Again a GET …/prices will be an absolute non-sense, it will be chosen to be forbidden by the guidelines, and even more, something worse, a GET …/prices?product=5687356785432 which is putting a concept-resource necessary to compute the price in the query param area would be an aberration …

Please note that we are putting resources always in a plural form even for a proven singleton.

We are also against the fact to put attributes/properties of a concept-resource in a resource path except obviously the main identifier required to obtain the access to a specific instance of a concept-resource (again that can be called resource …).

The term “facet” is an example, but your guidelines should fix it in order to not allow all terms in the query param area of a GET.

Another example to drive the point home: the notion of “recommendation” in a university for example. During its subscription, a course is not available anymore so, the system will have to propose, according to the student status, a set of alternative courses. Is it a (concept-) resource?

Again, you can create a “Recommendation repository” but is it a real metamodel object, a Master Data object or again “just” a facet?

It is a kind of “on the fly” computation of the available “course” resources. Not even sure that the result will be stored. It is not a Master Data because it is a computed set of “courses” than can be contextualized according to several elements (candidate or student, location, schedule, … these elements, by the way, could be properties of the candidate).

Can be recommended something like:

GET …/candidates/{ca_id}/courses/{co_id]?facet=recommendations

instead of a

GET …/candidates/{ca_id}/courses/{co_id]/recommendations again allowed, according to the definition and the reminder of Fielding.

These articles will be a mean to share usual issues and trying to solve it : everything can be criticized … but, again these problems must be dealt with your company or your organization in order to accelerate exposition of APIs and to build the best API catalogue possible as an accelerator for internal and external digitalization in logic, readable and usable ways.

But, do not forget, during the exposition the more rigorous you are, the more free you can be for the API and the webservice backend area (REST or not). So, stay tuned!

#2 - Should we put an operation (an action, a step of the lifecycle) in the API resource path?