New ask Hacker News story: Swagger/OpenAPI examples are bad, like reaaalllyy bad
Swagger/OpenAPI examples are bad, like reaaalllyy bad
3 by d3nigma | 1 comments on Hacker News.
While reading about the OpenAPI spec, I found these examples for "good" APIs: - https://ift.tt/3bVvlhp (older version) - https://ift.tt/3tbXg52 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?
3 by d3nigma | 1 comments on Hacker News.
While reading about the OpenAPI spec, I found these examples for "good" APIs: - https://ift.tt/3bVvlhp (older version) - https://ift.tt/3tbXg52 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?
Comments
Post a Comment