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.

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

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?

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.