How to Build APIs - MHacks 2016
1 like715 views
The document outlines the essential aspects of building APIs, focusing on design principles, testing, scaling, and infrastructure. It emphasizes the use of specifications like OpenAPI, the REST architecture, and best practices for handling resources and versioning. Additionally, it discusses security measures, monitoring, and the importance of having a developer portal for API management.
How to Build APIs - MHacks 2016
- 1. How to build APIs Target - Dan Cundiff (@pmotch) - MHacks 2016
- 3. Why do companies have them?
- 5. We’re really talking about building web apps.
- 6. ● We know how to test web apps ● We know how to scale web apps ● Infra-as-code ● Continuous integration ● Continuous delivery ● Immutable infrastructure ● etc
- 8. Use an spec framework: ● OpenAPI (aka Swagger) ● API Blueprint ● RAML
- 9. Design-first approach using API spec.
- 10. About REST
- 11. There is no one REST. There are choices to make.
- 12. Collections of resources Plural noun (let the http method be the verb)
- 13. /cars/
- 14. 5 things I can do to that collection: ● GET /cars/v1/ - list of cars ● POST /cars/v1/ - create a car ● GET /cars/v1/{car_id} - get a car ● PUT /cars/v1/{car_id} - update a car ● DELETE /cars/v1/{car_id} - delete a car
- 16. ● Version your APIs ● Breaking change = new major version ● Just follow semver.org
- 17. Filter the list: GET /cars/v1?model=ford&color=red
- 18. For attributes that don’t appear in the data model, do: GET /cars/v1/search? some_attribute_not_included_in_data_ model=xyz
- 19. Even transactional events are collections (e.g. sending an email, a door opening, etc.)
- 20. POST /door_openings/v1 ● POSTs and GETs ● Give door opening event an id
- 21. POST /inventory_updates/v1 ● Avoid race conditions ● Don’t do: PUT /inventory/{item_id}
- 22. Use paging for lists of things.
- 23. Use a chosen query param for partial responses.
- 24. Use normal http codes.
- 26. Avoid: ● Avoid XML ● SOAP died in 2007
- 27. Use TLS, just do it. istlsfastyet.com
- 28. Oauth, HMAC, basic auth.
- 29. ● /cars/v1/{car_id}/owners/{owner_id} is cool too ● Rate limiting ● Operators
- 30. API Gateways are useful.
- 31. Measure your APIs: ● Centralize logs ● Collect metrics
- 33. You need a developer portal.
- 34. Dev portal: ● docs ● forums ● key material, etc.
- 35. Making your API public or not
- 36. Reading: ● Follow API devs on twitter ● HN, API Evangelist, InfoQ conf vids, etc
- 37. You should come work for Target.
- 38. Questions?