Search code examples
jsonswaggerhateoasjson-ldswashbuckle

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

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.

Solution

  • 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