Does Swagger 2.0 enable impure REST API design?

Question

The current Swagger spec claims that Swagger is used to describe and document RESTful APIs. I think this is not the case rather I think Swagger is useful for simply describing a HTTP API for a few reasons:

1. The Swagger spec has elements like Path and Definition but they don't clearly map to the REST data elements like resource, representation, and media types. My thought is that to effectively describe a REST API, you should be required to define the explicit REST data elements in the context of your API.
2. Hyperlinks are not first class objects in the Swagger spec and thus hyperlinks and their critical descriptive attribute, link relation, can easily be left out. In fact, hyperlinks are not mentioned at all.
3. HTTP paths are at the front-and-center which seems to be a clear violation of a point Fielding made in his famous blog post:

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server)

Essentially, I think APIs defined using the Swagger 2.0 spec leads you to design an API that isn't constrained by HATEOAS which would violate REST.

Is this correct or am I missing something?

Answer 1

I absolutely agree. Swagger is not well suited for defining truly REST compliant APIs. The problem is that people define REST in a lot of different ways. The Richardson Maturity Model helps describe these different definitions.

Level 0 REST APIs pipe all requests through one URI and one HTTP method. This level includes any API that uses HTTP no matter how limited. In practice, people rarely call this REST anymore, but it does happen (probably for marketing reasons).

Level 1 REST APIs employ many URIs, but still only use one HTTP method (usually POST). Again, in practice, this rarely called REST anymore, but there was a time when it was common.

Level 2 REST APIs are where the concepts of resources and uniform interface are introduced. These APIs have URIs that represent resources and use the HTTP methods to perform CRUD operations on those resources. In practice, people started referring to this as RESTful to distinguish it from Level 1. I credit Ruby on Rails for popularizing this interpretation of REST, but I can't back that up. In any case, when Swagger claims to be for describing RESTful APIs, Level 2 is the definition they are referring to.

Level 3 REST APIs are fully compliant with the REST architectural style. In particular, they are characterized by using HATEOAS. All of the concerns you laid out in your question aren't taken into account until this level. In practice, some people have started calling these Hypermedia APIs to distinguish them from the now entrenched definition of RESTful as referring to the Level 2 definition.

I would say that your understanding of REST is more "mature" than that used by Swagger and therefore, you will only be frustrated trying to use it (I speak from experience). My personal choice for defining Hypermedia APIs is JSON Hyper-Schema. It can't match all the great tools Swagger has, but it allows me to write APIs at Level 3. That's more than I can say for any of the popular API definition languages out there.