Should you Combine Swagger with HATEOAS/HAL/JSON-LD?

Question

I am using Swagger for my ASP.NET Core API using Swashbuckle which describes my API in a separate document and provides a nice UI for all of this information.

Are there any advantages of using something like HATEOAS, HAL or JSON-LD which modify the document itself in combination with Swagger?

Here is an example of someone using Swagger with HAL.

Obnubilate

Answer 1

Like sampada stated both - swagger and HATEOAS - adds more value to different dimensions of your api.

Swagger will add value to the development lifecycle, making your api more understandable and browsable at development time.

HATEOAS will add value to your api when used by clients. The links provided by HATEOAS gives you the possibility to link different parts (i.e.: resources) of your api without needing to hardcode those links in your apps client code.

Assuming you have a contract with a couple of documents related to it. One quite common way to model this would be by using two resources:

• Contract Resource - given you operations to list, add, delete, change contracts;
• Documents Resource - given you operations to list, add, delete, change documents

To link those two together you might add fields in both resources models containing arrays of the related resource. Additionally you have to implement those implicit knowledge in your client application too. This way you (will) add clutter to your resources representations over time, polluting it with information about relations to other objects.

This is where HATEOAS comes into play, both moving those realtionship information out of your business objects and providing an unified way to handle those relationsships. Both resources business objects would now include one standardized header or value-field containing the information about all relations of the current resource. E.g. One contract resource would now have 3 links with rel-attribute "document" linking to the appropriate document resources and 1 link with rel-attribute "order" linking to the order this contract resulted from.

As far as i know JSON-LD is used to normalize the vocabulary of different APIs, making it easier to use them side-by-side. Some might use firstName & lastName as a Person objects property, while others would have a called the properties givenName & familyName. With JSON-LD you can map both objects to a common name. You might consider having a look at this link: DZone - Json-LD

Heterozygous

Answer 2

There are definite advantages of integrating HATEOAS into your API code in addition to using Swagger.

Swagger adds form to your APIs by making them look good and presentable so that client code can be written easily, at the same time it also makes documentation a much less boring task by integrating it with code. Needless to say, it also saves the extra time it takes to document if done after coding is over. In this sense, it is a bit revolutionary.

HATEOAS on the other hand makes your APIs self discoverable by enabling Level 3 RMM . This makes it easier to navigate through one API to the other. The idea is to have a base URL that a client can use and the rest of the REST APIs are discovered from this base URL.

Now the question is, why have both? Well, it just adds more dimension to your Restful APIs and gives clients more choice for very little coding effort. Who wouldn't want that?

Bratton

As a developer, I'd personally just look at and try the Swagger UI and I think most other developers would do the same. Are the other HATEOAS options more useful for making your API machine readable? Also, HATEOAS usually makes the JSON harder to consume by apps because you have additional noise (Is the solution that you only respond with HATEOS if someone asks for it by MIME type?). – Obnubilate

Like i said, HATEOS will make your API Level 3 compliant. This effectively means the responses will include _self, _next and _previous links. This makes navigation real easy for the client UI. I agree that it does tend to get chatty, but then its up to you as a developer how many links to include. – Bratton

@MuhammadRehanSaeed I think it's important to understand what you refer to as noise is actually the AS in the HATEOAS. The presence of a link relation signifies to the client the current state of the resource, so it may mean that the document, although editable in general, cannot be edited now because another user locked it, or the document is in review state, or some other policy disallows it now, etc. This way the client is separated from the business logic of the state and all it needs to know is how to see what it can do with the resource (the link relation types). – Tove

@MuhammadRehanSaeed to add to what i said, this separation actually ends up simplifying the client (even though the payloads look busier). 1 from my above example, the client doesn't have to know what determines editability of a resource which makes it simpler and any changes in that do not require client changes, 2 if you deal with UI, you can now build generic components which expose edit for any resource type as this is always exposed the same way – Tove

Answer 3

Consider looking into Hydra:

http://www.hydra-cg.com/

Hydra is a vocabulary for JSON-LD which allows you to embed hypermedia controls into your data. Additionally, you can provide an API Documentation endpoint plays a similar role to the Swagger definition. What I like about Hydra is that the hypermedia controls are baked into the responses rather living out of band in a service definition of some sort. JSON-LD and Schema.org are definitely worth looking into given how both Google and Microsoft are supporting them in their products.

Hydra is still relatively new, so the available tooling isn't as strong as it is for Swagger.

Promising