Best Practice in API Design

API theory and some design pointers for my talk at Hackference 2013 in Birmingham

Transcript

1. Best Practice in API Design
2. About Me • Lorna Jane Mitchell • http://lornajane.net • API and Web Development Consultant • Author, speaker
3. Why APIs? APIs provide: • Re-usable business logic • Scalability • 3rd party access • Maintainability
4. 3 Stages of API Development There are various stages of building an API 1. Publish an API 2. Consume your own API 3. Modular/Multiple APIs
5. Web
6. Service
7. Design
8. Web
9. HTTP
10. Request and Response
11. Statelessness
12. Status Codes
13. Status Codes: Headline News Common codes: 200 OK 304 Not Modified 302 Found 301 Moved 401 Not Authorised 403 Forbidden 404 Not Found 500 Internal Server Error
14. Headers
15. HTTP Headers Headers are the metadata about the content we send/receive Useful headers: • Accept and Content-Type: used for content format negotiation
16. Content Negotiation
17. HTTP Headers Headers are the metadata about the content we send/receive Useful headers: • Accept and Content-Type: used for content format negotiation • User-Agent: to identify what made the request
18. HTTP Headers Headers are the metadata about the content we send/receive Useful headers: • Accept and Content-Type: used for content format negotiation • User-Agent: to identify what made the request • Set-Cookie and Cookie: working with cookie data
19. HTTP Headers Headers are the metadata about the content we send/receive Useful headers: • Accept and Content-Type: used for content format negotiation • User-Agent: to identify what made the request • Set-Cookie and Cookie: working with cookie data • Authorization: controlling access
20. Verbs
21. HTTP Verbs • More than GET and POST • PUT and DELETE to update and delete in a RESTful service • HEAD, OPTIONS and others also specified In REST, we use: GET Read POST Create PUT Update DELETE Delete
22. Service
23. Target Audience
24. RPC Services
25. RPC: Remote Procedure Call • Single endpoint • Function name • Parameters • Return value • SOAP is a kind of RPC
26. Soap
27. Data Formats
28. REST
29. RESTful Services • REpresentational State Transfer • URLs are unique resource identifiers • HTTP verbs indicate which operation should happen • We have full CRUD operations on a series of resources
30. Design
31. Heartbeat
32. Versioning
33. Consistency
34. Caching
35. Handling Errors
36. Access Control
37. Delivery and Support
38. Web Service Design
39. Thanks! http://joind.in/8855 @lornajane http://lornajane.net/