Building apis that don’t suck!
Download as PPTX, PDF0 likes320 views
The document discusses best practices for building effective APIs, emphasizing the correct use of HTTP verbs and endpoint structure, while advocating for user-centered payload design. It highlights the importance of using appropriate HTTP status codes and resource relationships, along with the benefits of versioning and documentation practices. The author encourages developers to be thoughtful and consistent in their API design, adhering to established standards while being mindful of potential complexities.
![HATEOAS & being RESTful
2. Hypermedia
Controls
"data": {
"type": "users"
"attributes": {
....
},
"links": [ {
"rel": "self",
"uri": "/users/1"
}, {
"rel": "checkins",
"uri": "/users/1/checkins"
}]
}](https://image.slidesharecdn.com/buildingapisthatdontsuck-170921034822/85/Building-apis-that-don-t-suck-11-320.jpg)
Building apis that don’t suck!
- 1. Building APIs that don’t suck! (To be taken with a grain of salt)
- 2. Why?
- 3. Endpoint Theory Noun vs Verb POST /users POST /users/create
- 4. Resources are Nouns Verbs can be made Nouns POST /users/123/checkin POST /users/123/checkins
- 5. Endpoint Theory contd... Singular vs Plural GET /users/1,GET /users GET /user/1, GET /users
- 6. Use HTTP Verbs appropriately GET Retrieve GET /users/123 POST Create POST /users PUT Replace PUT /users/123 PATCH Update PATCH /users/123 DELET E Delete DELETE /users/123
- 7. Resource Relationships - keep it simple GET /users/1/checkins GET /users/1/checkins/123 GET /checkins/123
- 8. Use HTTP Status Codes appropriately 2xx Success 200(OK), 202(Created) 3xx Redirect 301(Redirect), 303(Moved Permanently) 4xx Client Error 400(Bad Req), 401(Unauthorized), 404(Not Found), 422(Unprocessable) 5xx Server Error 500(Internal Err)
- 9. Payload Design - think of the user { "data": { "type": "entity_type" "attributes": { .... } } } { "errors": { "status": 422, "title": "Bad api call", "detail": "Details...” } }
- 10. HATEOAS & being RESTful 1. Content Negotiation Hypermedia As The Engine Of Application State GET /configs HTTP Header: Accept: application/x-yaml
- 11. HATEOAS & being RESTful 2. Hypermedia Controls "data": { "type": "users" "attributes": { .... }, "links": [ { "rel": "self", "uri": "/users/1" }, { "rel": "checkins", "uri": "/users/1/checkins" }] }
- 12. FAQ Versioning - Semantic Versioning (http://semver.org) Documentation - Slate or Swagger Testing - JSON-Schema validation Standards - JSON-API, but I can’t recommend it! UGLY Parts - Filtering, Foreign-Key relations, Sideloading GraphQL - Not a REST API, Infinite API
- 13. Take Away API Be thoughtful when designing APIs Follow good practices Stay consistent Try not to break it (Semantic versioning) TLC
- 14. Thank you “Life is short.. Work somewhere awesome” http://www.enova.com
Editor's Notes
- #3: I wanted to get myself to read the book. So I signed up for an Enova tech tech talk, where I work.
- #4: Prefer nouns to verbs to represent endpoints. Why? Because URLs represent a Resource which lives on the Internet. It’s a thing (noun)
- #5: You can still make a verb into a noun if needed. Eg. checkin is an action but checkins a list of checkins. Like a verb but Likes a noun.
- #6: Use Plural. Don’t use both. It’s more consistent and less ambiguous
- #7: Verbs exist in the REST world. But use the HTTP built-ins to achieve it.
- #8: Best not to go more than 1 level deep. If you need to do the 2nd example, do the last one instead
- #9: Use HTTP status to convey how things went. Make a best effort to use the correct http status code (even though there are overlapping codes)
- #10: Highly subjective, but try to come up with a payload design and try to be consistent. This design is inspired by json-api. Why not json-api? It can get too complex and ugly
- #11: It ain’t RESTful if it doesn’t have HATEOAS. That’s what Roy Fielding, the inventor or REST says. Content negotiation not a big deal these days since it’s pretty much json.
- #12: However supporting hypermedia links is important. It promotes organic API discoverability.
- #13: Times almost up. The one I spent some time talking about is API testing via json-schema. I think it can be used to address most of API testing. If you want to be exact then use more exact matching of data against a golden file but IMHO that isn’t really needed here.
- #14: Good API design is important. It imputes thoughtfulness into a well designed system (even if that is not the case :). Don’t think of APIs as web page replacements. Instead think of them as schemas and data. Thinking of good API designs may invite to re-evaluate current design decisions and set you on a path to simplicity nirvana.