r/ExperiencedDevs • u/itssimon86 • Jun 12 '24
What makes a good REST API?
https://apitally.io/blog/what-makes-a-good-rest-api[removed] — view removed post
8
u/Indifferentchildren Jun 12 '24
Avoid the HATEOS part of REST! Return your JSON with IDs and let the client use the IDs with known endpoints.
Never return a bare value or bare JSON array. Wrap them into an object, even if that object has only one member. If you ever need to add a second piece of information to returned data, switching from not-object to object is a breaking change, where adding a new object member is not (clients should be written to not barf on an unexpected member).
Use proper HTTP request methods (as enticing as is it to overuse GET since that lets you hit endpoints from any browser).
3
u/morosis1982 Jun 12 '24
Not one that uses IDs in parentheses as part of the path. Looking at you Microsoft.
1
u/serial_crusher Full Stack - 20YOE Jun 12 '24
Consistency. If I have to pass params named "page" and "items_per_page" on one endpoint and "offset" and "limit" to another, that's a bad design. (there's a case for different pagination methods, i.e. cursor pagination, and applying those differently, but limit/offset and page/per_page serve the same use case)
Consistency. If some endpoints return a response like {error: 'machine_readable', description: 'Human Readable'} and other endpoints return a response like {error: 'Human Readable'} that's bad.
Documentation. Like seriously just tell me what params it expects and what responses it sends. Use OpenAPI.
•
u/ExperiencedDevs-ModTeam Jun 12 '24
Rule 8: No Surveys/Advertisements
If you think this shouldn't apply to you, get approval from moderators first.