Swagger/OpenAPI examples are bad, like reaaalllyy bad
9 comments
It feels like you're attacking a design without understanding the design principles behind it.
Looking at https://petstore3.swagger.io, the API is `/pet` (singular), because that's exactly what it represents: the type of a singular pet. This design choice has to do with orthogonality: for example, what is `POST /pets` supposed to do? Create a new list of pets? That makes no sense. If you want to argue that it should create a new pet, then that makes no sense either, because the endpoint is explicitly about a collection of pets. This distinction may seem like nitpicking, but consider an entity type of ambiguous plurality like `/group`. You want to be clear about whether an action on this endpoint applies to a `group` or to individual entities in the group and you want that semantic to be consistent with other endpoints.
On the same vein about orthogonality, `/user/{action}` is orthogonal to `/pet/{action}` in the sense that they both follow the same OOP-ish pattern. Calling an endpoint merely `/login` doesn't fit into that mold (e.g. Can a pet login? Why is `/login` floating without a noun, but `DELETE /user/{id}` isn't? etc)
The choices of PUT and POST have to do with what the HTTP spec says about idempotency. `PUT /pet` must be idempotent (i.e. upsert a pet), `POST /pet` is not idempotent (i.e. create a pet).
`POST /pet/{id}` is a bit of a seemingly counterintuitive one, but again it has to do with idempotency. It's actually a deliberate choice to indicate that there may be internal logic that isn't pure (for example, there may be a lastModified field).
Looking at https://petstore3.swagger.io, the API is `/pet` (singular), because that's exactly what it represents: the type of a singular pet. This design choice has to do with orthogonality: for example, what is `POST /pets` supposed to do? Create a new list of pets? That makes no sense. If you want to argue that it should create a new pet, then that makes no sense either, because the endpoint is explicitly about a collection of pets. This distinction may seem like nitpicking, but consider an entity type of ambiguous plurality like `/group`. You want to be clear about whether an action on this endpoint applies to a `group` or to individual entities in the group and you want that semantic to be consistent with other endpoints.
On the same vein about orthogonality, `/user/{action}` is orthogonal to `/pet/{action}` in the sense that they both follow the same OOP-ish pattern. Calling an endpoint merely `/login` doesn't fit into that mold (e.g. Can a pet login? Why is `/login` floating without a noun, but `DELETE /user/{id}` isn't? etc)
The choices of PUT and POST have to do with what the HTTP spec says about idempotency. `PUT /pet` must be idempotent (i.e. upsert a pet), `POST /pet` is not idempotent (i.e. create a pet).
`POST /pet/{id}` is a bit of a seemingly counterintuitive one, but again it has to do with idempotency. It's actually a deliberate choice to indicate that there may be internal logic that isn't pure (for example, there may be a lastModified field).
I think you are overreacting.
Even if you were right (which I don't agree is the case) you need to understand the examples are not there to teach you good API design.
The Pet Store is a Hello World of APIs and the point of this example is to replicate an example that is already known to people from other frameworks/libraries.
The point is to show OpenAPI on an example that is, hopefully, already familiar to the user.
It is as if you were arguing how Hello World! should be capitalized or whether there should be a comma in it or not.
Even if you were right (which I don't agree is the case) you need to understand the examples are not there to teach you good API design.
The Pet Store is a Hello World of APIs and the point of this example is to replicate an example that is already known to people from other frameworks/libraries.
The point is to show OpenAPI on an example that is, hopefully, already familiar to the user.
It is as if you were arguing how Hello World! should be capitalized or whether there should be a comma in it or not.
>Do I not know the latest API design principles yet or why are the examples for a de facto industry standard so lousy?
Swagger/OpenAPI is not really a standard, it's just a way to document an API. JsonAPI [1] is an example of a standard.
I only have a few years of API development under my belt, but something I have learned is that consumers of APIs really don't care about any of the points you listed. No one really cares if your API does not strictly follow ReST principles. They care that it works, that it's fast, and that it's well documented, in that order. Sure, using all the different HTTP verbs feels nice as a developer, but you know what is much simpler for everyone? GET for all reads and POST for all writes.
To be clear, I am not saying that you should give up on following best practices in your APIs. What I am saying is that you should design your APIs to meet your clients' needs, not to satisfy "principles of good API design."
[1]: https://jsonapi.org
Swagger/OpenAPI is not really a standard, it's just a way to document an API. JsonAPI [1] is an example of a standard.
I only have a few years of API development under my belt, but something I have learned is that consumers of APIs really don't care about any of the points you listed. No one really cares if your API does not strictly follow ReST principles. They care that it works, that it's fast, and that it's well documented, in that order. Sure, using all the different HTTP verbs feels nice as a developer, but you know what is much simpler for everyone? GET for all reads and POST for all writes.
To be clear, I am not saying that you should give up on following best practices in your APIs. What I am saying is that you should design your APIs to meet your clients' needs, not to satisfy "principles of good API design."
[1]: https://jsonapi.org
I agree with your post completely except for the importance of speed.
I would rate documentation above speed in my evaluation of an api. If its not documented I can't use it, regardless of how fast if is - if its documented badly and I can't easily use it, I quickly move on to an alternate offering.
Fast is great, and important, and nice to have, but documentation is a deal breaker.
I could go further and say that docs are even more important than "it works" because without docs my definition of "works" may be different to the authors intent.
I would rate documentation above speed in my evaluation of an api. If its not documented I can't use it, regardless of how fast if is - if its documented badly and I can't easily use it, I quickly move on to an alternate offering.
Fast is great, and important, and nice to have, but documentation is a deal breaker.
I could go further and say that docs are even more important than "it works" because without docs my definition of "works" may be different to the authors intent.
Is this about the semantics and syntax of English? Would your response be different in a hypothetical language where the pluralistic pet is (s)pet? How about if the plurality of pet was "scront" or "pet, uncountable many"
Mapping English words with / as a separator and into a world of 4 or 6 action verbs is a huge constraint on "meaning" in the linguistic sense.
Mapping English words with / as a separator and into a world of 4 or 6 action verbs is a huge constraint on "meaning" in the linguistic sense.
Your points may be valid, but do these points qualify as “like reaaalllyy bad”, of course not.
We’re quite a few to think that REST api design principles are silly, dand that people who impose their view / mock others for not following them strictly are mindless zealots.
We’re quite a few to think that REST api design principles are silly, dand that people who impose their view / mock others for not following them strictly are mindless zealots.
You appear to be relying on a working example intended as a visualization tool to go alongside some really dry reference documentation as a guide for good API design.
I agree with you 100%. There are very good and valuable reasons to follow some of the purist “rules” around designing REST APIs. It makes them significantly easier to consume when they don’t violate the principle of least astonishment.
- https://petstore.swagger.io/ (older version)
- https://petstore3.swagger.io/
However, imho they are really bad examples as they do not follow basic principles of good API design. Here are some reasons:
1. They use "/pet" instead of "/pets" for the pet collection (Besides the fact that "/pets" isn't even an endpoint and you can not get a list of all pets ^^).
2. The login & logout endpoints are under /user (i.e. /user/login, /user/logout)
3. You do not use PUT on a collection as they did with PUT /pet
4. You do not use POST as they did with /pet/{pet_id} to update a single resource.
5. You do not use POST to create a resource and PUT to update the same resource as they did with PUT /pet and POST /pet
Some might argue that it is a matter of opinion that these examples are bad. You may be right, but at minimum an API should be self-consistent. But even that is not the case here.
That's why I'm wondering what this is all about. Do I not know the latest API design principles yet or why are the examples for a de facto industry standard so lousy?
And btw what is your opinion on the API design of the examples?