Can anyone explain the difference between Swagger & HATEOAS? I have searched this question many times but nobody has provided a proper, detailed answer differentiating these two aspects.
Difference between Swagger & HATEOAS
Asked Answered
The main difference between Swagger and HATEOAS IMO, which is not covered in the accepted answer, is, that Swagger is only needed for RPC'esque APIs. Such APIs, however, have actually hardly anything to do with REST.
There is a further, widespread misconception that anything exchanged via HTTP is automatically RESTful (~ in accordance with the REST archtitectural style), which it is not. REST just defines a set of constraints that are not choices or options but are mandatory. From start to finish. There is nothing wrong from being not RESTful, but it is wrong to term such an architecture REST.
Swagger describe the operations that can be performed on an endpoint and the payload (including headers and the expected representation formats) that needs to be sent to the service and also describe what a client might expect as response. This allows Swagger to be used both as documentation as well as testing-framework for the API. Due to the tight coupling of Swagger to the API it behaves much like a typical RPC service description, i.e. similar to WSDL files in SOAP or stub or skeletton classes in RMI or CORBA. If either the endpoint changes or something in the payload changes, clients implementing against a Swagger documentation will probably break over time just reintroducing the same problems typical RPC implementations have.
REST and HATEOAS, on the other side, are designed for disovery and further development. REST isn't a protocol but an architectural style to start with that describes the interaction flow between a client and server in a distributed system. It basically took the concepts which made the Web so successful and translated it onto the application layer. So the same concepts that apply to the browsable Web also apply to REST. Therefore it is no miracle that also HATEOAS (the usage of and support for links, link relations and link names) behave similar to the Web.
On designing a REST architecture it is benefitial to think of a state machine where a server provides all of the information a client needs to take further actions. Asbjørn Ulsberg held a great talk back in 2016 where he explains affordances and how a state machine might be implemented through HATEOAS. Besides common or standardized media-types and relation names no out-of-band knowledge is necessary to interact with the service further. In the case of the toaster example Asbjørn gave in his talk, a toaster may have the states off, on, heating and idle where turning a toaster on will lead to a state transition from off to on followed by a transition to heating till a certain temperature is reached where the state is transitioned to idle and switches between idle and heating till the toaster is turned off.
HATOAS will provide a client with the information on the current state and include links a client can invoke to transition to the next state, i.e. turning the toaster off again. It's important to stress here, that a client is provided by the server with every action the client might perform next. There is no need for a client implementor to consult any proprietary API documentation in order for a client to be able to interact with a REST service. Further, URIs do not have to be meaningful or designed to convey a semantical-expressive structure as clients will determine whether invoking that URI makes sense via the link-relation name. Such relation names are either specified by IANA, by a common approach such as Dublin Core or schema.org or by absolut URIs acting as extension attributes which might point to a human-readable description, which further might be propagated to the user via mouse-over tooltips or such.
I hope you can see by yourself that Swagger is only needed to describe RPC Web-APIs rather than applications that follow the REST architectural design. Messages exchanged via REST APIs should include all the information needed by a client to make informed choices on the next state transition. As such it is benefitial to design such message flows and interactions as state machine.
Update:
How are Swagger and HATEOAS mutually exclusive? The former documents your endpoints (making auto-generating code possible) and the latter adds meta-information to your endpoints which tell the consumer what they can do (i.e. which other endpoints are available). These are very different things.
I never stated that they are mutually exclusive, just that they serve two different purposes, where if you follow one approach the other gets more or less useless. Using both does not make any sense though.
Let's move the discussion to the Web domain as this is probably more easily understandable and REST is de facto just a generalization of the concepts used on the Web, so doing this step is just natural and also a good recommendation in terms of designing REST architectures in general. Think of a case where you as a user want to send some data to the server. You have never used the service before so you basically don't know how a request has to look like.
In Swagger you would call the endpoint documentation, select the option that most likely might solve your task, read up on how the request needs to look like and hack a test-case into your application that ends up generating a HTTP request that is sent to the respective location. Auto-generating code might spare you some hacking time, though you still need to integrate the stub classes into your application and test the whole thing at least once just to be safe. If you later on need to integrate a second service of that API or of yet an other API in general, you need to start from the beginning and look up the Swagger documentation, generate or hack the interaction code and integrate it into your domain. Plenty of manual steps involved and in cases of API changes you need to update your client as otherwise it might stop working.
In the Web example however, you just start your browser/Web client, invoke the respective URI that allows you to send the data to the server and the server will most likely send you a HTML form you just need to fill out and click the send button which automatically sends the request to the server which will start to process it. This is HATEOAS. You used the given controls to drive your workflow. The server taught your client every little detail it needed to make a valid request. It served your client with the target URI to send the request to, the HTTP method it should use and most often also implicitly the media type the payload should be in. In addition to that it also gave your clients a skeleton of the expected and/or supported elements the payload should contain. I.e. the form may require you to fill out a couple of input fields, select among a given set of choices or use some other controls such as a date or time picker value that is translated to a valid date or time representation for you. All you needed to do was to invoke the respective resource in your Web client. No auto-generation, no integration into your browser/application. Using other services (from the same or different providers) will, most likely, just work the same way so no need to change or update your HTTP client (browser) as long as the media-type request and responses are exchanged are supported.
In the case where you rely on Swagger RPC'esque documentation, that documentation is the truth on how to interact with the service. Mixing in some HATEOAS information doesn't provide you any benefits. In the Swagger case, carrying around additional meta-information that bloat up the request/response for no obvious reasons, as all the required information is given in the reference documentation, will, with some certainty, lead to people starting questioning the sanity of the developers of that service and ask for payload reduction. Just look here at SO for a while and you will find enough question asking on how to optimize the interaction further and further and reducing message size to a minimum as they process every little request and don't make use of response caching at all. In the HATEOAS case, pointing to an external reference is just useless as peers in such an architecture most likely already have support for the required necessities, such as URI, HTTP and the respective media types, implemented into it. In cases where custom media-types are used, support can be added at runtime via plug-ins or add-ons dynamically (if supported).
So, Swagger and HATEOAS are not mutually exclusive but the other gets more or less useless once you decided for one route or the other.
@sanket jaiswal If you look at an example like the petstore you clearly see that it defines endpoints, HTTP methods and parameters that need or can be passed to the service. This is very similar to WSDL or stub classes i.e. which do the same thing. They basically provide the interface on how to interact with the service. A client implementing such a specification might break easily if the API is changed and thus needs to be updated as well. Implementing such an API will also only work on that API not on any other API as well. –
Dundalk
@sanket jaiswal This is basically just the opposite of HATEOAS where the same technique and approach works for every API –
Dundalk
How are Swagger and HATEOAS mutually exclusive? The former documents your endpoints (making auto-generating code possible) and the latter adds meta-information to your endpoints which tell the consumer what they can do (i.e. which other endpoints are available). These are very different things. –
Spinoff
@Spinoff As answering your comment needed a bit of explanation, I integrated my response into the answer –
Dundalk
Swagger: Swagger aids in development across the entire API lifecycle, from design and documentation, to test and deployment. (Refer to swagger.io)
HATEOAS: Hypermedia as the Engine of Application State
An Ion Form is a Collection Object where the value member array contains Form Fields. Ion Forms ensure that resource transitions (links) that support data submissions can be discovered automatically (colloquially referred to as HATEOAS). (Refer to https://ionspec.org/)
One is a framework for supporting designing and testing for APIs, the other is an API design architecture.
Can you explain the UseCases Both of Them @Varun –
Bigamist
HATEOAS Architecture lets us decide flow to be,HTTP API being stateless, this architecture helps us know the present state and next state it can be for eg. through HATEOAS architecture i can design an API which shows the present state of my API, just like my web browser's current state. With this API Design i will have link to next API endpoint where i want to go through that API endpoint. –
Donnenfeld
Using swagger i can get the entire documentation generated of my code automatically and it will provide me a testing playground. This will reduce my task of creating documentation and i can focus on testing. –
Donnenfeld
Should i add something more @sanketjaiswal ? –
Donnenfeld
We can say that Swagger is portfolio of REST End @Varun –
Bigamist
It would also help you to present your REST API to clients is that –
Bigamist
We can consider it like a portfolio because it is one stop for presenting all the details about the API, it is available at <my-url>/swagger/index.html We can test out API from that point also. We can also generate swagger client code from swagger json endpoint mostly available at <my-url>/swagger/v1/swagger.json –
Donnenfeld
Building a RESTful API is not a binary concept. That is why we use the Richardson maturity model in order to measure how RESTful an API is.
Based on this maturity model
- At level 0 we provide mechanisms for client of the API to call some methods on the server (Simple RPC)
- At level 1 we expose resources on the server so the client of the API can have direct access to the resources that it requires (exposing Resources)
- At level 2 we provide a uniform way for the client of the api to interact with the API (exposed resources) and the HTTP protocol has these methods (using HTTP verbs to interact with resources).
- the ultimate step is to make our api explorable by the client. HATEOAS provides such functionality (over HTTP) meaning that it adds relevant links and affordances (extra methods) that can executed on the resource so the client of the API can understand its behavior.
Based on these definitions in properly designed RESTful API there is no coupling between client and server and client can interact with the exposed endpoints an discover them.
On the other hand, swagger is a tool that helps you document your API along with some extra goodies (code generators).
I believe that Swagger (with the help of swagger Hub) provides services for implementing a RESTful endpoint with maturity levels up to 2. But it does not go any further and it does not provide proper support of HATEOAS.
You can define your resources and HTTP verbs in (json/yml) files. And based on this definition Swagger can generate API documentation and the extra goodies (client stubs and skeletal implementation of the server API).
For all those people who have worked with Java RMI, SOAP,... the extra goodies part is a reminder of old technologies where there was tight coupling between Client and Server because the stubs and skeletal implementations are all built based on the same API definition file.
There is no level of RESTfulness. Your server either adheres to the constraints imposed by the REST architecture or it dosn't. Also, the Richardson maturity model (RMM) is flawed. I.e. there can't be any RESTfulness before level 3 and even at level 3 it might violate some of the constraints Fielding defined. Just look what the RMM says about media types or typed resources. Hence, please, do not use the RMM to define a level of RESTfulness –
Dundalk
by level 3 you mean (HATEOAS)? So what do you call an API that follows REST guidelines but has no support for HATEOAS? I still call it a REST API but not a complete RESTfull API. That is why we need a maturity model and of course, you can not call an API that does not use HTTP verbs (Communication protocol) properly, a REST API. Do you disagree with this statement? –
Schiro
Web API or something other. Most people have a false understanding of what REST is, hence there are so many "REST APIs" out there which are RPC through and through. For sure they haven't read Fielding's dissertation or other stuff he published on this topic or at least not understood correctly and therefore probably picked up their "understanding" by some other "source" that clearly didn't understand the idea of it at all. –
Dundalk
Just read through Fieldings famous rant and you might realize that there can't be any REST before level 3 at all and then read through the RMM once again and read what it states about media-types and content-type negotiation, which the Web and as such also REST relies on heavily. These are mechanisms to avoid typed resources that just introduce further coupling to the server side, which REST tries to avoid at all cost –
Dundalk
I completely agree that in order to have a RESTfull API we should have a content negotiation mechanism but HATEOAS is about the discoverability of an API in the link you provided this section talks about discoverability. –
Schiro
Lots of API developers skip this part (HATEOAS/discoverability) and instead choose to document their APIs using third-party tools like swagger. Adopting this approach prevents machines from automatically discovering the API and developer interaction is needed to read the documentation and modify the client code. We can still benefit from another aspects of a RESTfull API. –
Schiro
Links and discoverability are just one part of HATEOAS. Affordances expressed by hypertext, resource description via forms, link relation names and so forth all fall into this category. And sure, applications might benefit in the long run if they don't hardcode links but instead dynamically looking those up. That was not part of our discussion.
I still call it a REST API but not a complete RESTfull API Just because you can doesn't mean you should. That just falls into the category "I don't care what REST is, I just use what I need and blame REST when it doesn't uphold to its promises" –
Dundalk I don't know where are you getting with this. Nobody is blaming anyone for anything. Software development is about compromises. There are lots of guidelines and best practices but at the end of the day you what to deliver software and not demonstrating academic concepts. You are saying being RESTful is a binary concept but I am saying there's a gray area in between that most developers are following that path because of the lower cost of development and the benefits it provides compared to other approaches such as SOAP. have a nice day –
Schiro
© 2022 - 2024 — McMap. All rights reserved.