Do you know that OpenAPI (formerly "Swagger") and REST are two different things?
- A "pure" REST API should be self-descriptive (i.e., it doesn't require any documentation) by implementing the HATEOAS (Hypermedia as the Engine of Application State) principle. Clients interact with the API entirely through URLs provided by the server, without needing to know the structure of URLs in advance. This is similar to how browsers follow links.
- Most REST APIs today are not "pure". Clients still need documentation to use the API's endpoints effectively.
OpenAPI helps describe (or document) "impure REST APIs." But please don't confuse the two! OpenAPI doesn't enforce as many conventions as REST. For example:
| REST (or impure REST) | OpenAPI |
|---|---|
| - We have to choose the correct HTTP verb (PUT, POST, PATCH, etc.) for an API endpoint. - For “upsert” endpoints (50% update here and 50% insert there), these HTTP verbs often don’t make sense. |
No constraint: - You can simply use POST for all endpoints (like in the SOAP protocol). - Or, if you prefer the CQRS pattern: use GET for queries, POST for commands. |
| REST services often return fake technical errors for business logic errors: - Return HTTP 404 when a consumer queries something that is "not found" in the database. - Return HTTP 500 when the server does something wrong. ⇒ REST confuses consumers when a real technical error occurs. They might think it’s a normal business error if not handled carefully. Consumers often need to read the docs to differentiate between “HTTP 500 business error” and “HTTP 500 technical error.” |
No constraint: The following design is valid: Always return HTTP 200, even in case of a business error. (which means that Business Errors are returned as a normal HTTP 200 response) Consumers can naturally recognize technical errors: - HTTP 404 for a wrong URL endpoint - HTTP 500 for real technical errors on the server (e.g., load balancing issues, memory overflow) ⇒ Error handling is clearer and less ambiguous. |
Following (impure) REST conventions often leads to confusion for consumers—especially around error handling—and adds unnecessary complexity when choosing illogical HTTP verbs. OpenAPI helps document these inconsistencies. But more importantly, OpenAPI doesn’t force you to follow impractical REST conventions.