Building APIs

Transcript

1. Building APIs Justin Yost Web Developer at Loadsys 4 twitter.com/jtyost2 4 github.com/jtyost2 4 yostivanich.com
2. What is an API 4 API - Application Programming Interface 4 One thing talks to another thing. 4 Twitter, Facebook, AWS, all have APIs.
3. Why do you need an API 4 JS Front End Framework? 4 An app? 4 Talk to other servers than the ones you own/ provision?
4. Design 4 APIs are for developers 4 APIs are for in-house developers 4 APS are for outside developers 4 APIs are for possibly all level of developers
5. https://stripe.com/docs/ api
6. APIs are hard
7. Key Tips For Designing an API 4 Consistency 4 Standards (REST, HTTP, OAuth) 4 Versioning 4 Documentation (API Blueprint) 4 Don't just present the database
8. Consistency 4 Endpoints /people and /people/15 vs /person and /person/15
9. Consistency 4 Output { "people": { {"name": "First"}, {"name": "Second"} } } vs { "person": { "name": "First" } }
10. Standards 4 REST 4 OAuth 2.0 4 JSON (JSON API hit 1.0 recently)
11. REST Uniform Interface 4 System of endpoints 4 Provides enough information to be self describing 4 Provides enough information to manipulate 4 The interface is HTTP itself
12. REST Stateless 4 HTTP is Stateless by design 4 Web apps though tend to care about state 4 State is what stored information do I already know when you make the request (Session is State)
13. REST Cacheable 4 API should respond with Cache Headers as appropriate 4 API Clients should respect Cache Headers
14. REST Client-Server 4 Separation of Concerns 4 Client - presents data, protects user state 4 Server - stores data
15. REST Layered System 4 Clients may not always talk directly to the API server 4 Talk to an Auth Server, then a caching server, then API server
16. Design REST 4 REST enforces a pattern
17. Design REST 4 REST is HTTP 4 HTTP is more than GET, POST, PUT, DELETE 4 OPTIONS and HEAD 4 Idempotent Methods (GET, HEAD, DELETE, PUT) 4 Return Correct and Valid Headers
18. Design OAuth 2.0 4 http://oauth.net/2/ 4 https://aaronparecki.com/articles/2012/07/29/1/ oauth2-simplified 4 Short URL: http://jty.me/1dEQyge 4 Support for a variety of authentication schemes 4 Tons of pre-existing libraries and packages
19. Design JSON 4 Use JSON 1st and primarily 4 Maybe XML - are you a bank or law firm or Google? 4 Consider JSON API (Like really really consider it)
20. Design Versioning 4 /api/v1/foo 4 /api/foo HEADERS: {'api-v': '1.0'} 4 /api/foo HEADERS: {'Accept': 'application/ vnd.domain.v2+json'} 4 https://v1.domain.com/api/foo
21. Design Documentation 4 Clear 4 Complete 4 Examples (CURL, PHP, Java, Ruby, Node, Go, etc)
22. Design Documentation 4 API Blueprint: https://apiblueprint.org/ # GET /message + Response 200 (text/plain) Hello World!
23. Design Documentation 4 Dredd: https://github.com/apiaryio/dredd
24. Design Don't just present the Database 4 Database and API are different and unique 4 Think through the complex pieces of the API 4 APIs can make thins simpler in the final view
25. This stuff is really hard 4 You'll mess up 4 You'll forget something 4 You'll build it weird 4 That's why we version things
26. Some other tips 4 SSL 4 Build stuff with your API, that'll tell you how hard it is 4 Read other API docs and build with their API 4 Provide Libraries
27. Questions?