"Best Practice in API Design" talk given at phpday 2012 in Verona, Italy. This talk aims to give the best possible advice to anyone publishing a web service of any kind.

1. Best Practice in API Design

2. About Me
• Lorna Jane Mitchell
• http://lornajane.net
• PHP consultant, developer, trainer
• Author, speaker
2

3. Using APIs
There are various stages:
1. publish
3

4. Using APIs
There are various stages:
1. publish
2. dogfood
3

5. Using APIs
There are various stages:
1. publish
2. dogfood
3. modularity
3

6. Web

7. Service

8. Design

9. Web

10. HTTP

11. Request and Response

12. Statelessness

13. Status Codes

14. Status Codes: Headline News
Common codes:
200 OK
302 Found
301 Moved
401 Not Authorised
403 Forbidden
404 Not Found
500 Internal Server Error
12

15. Headers

16. HTTP Headers
Headers are the metadata about the content we send/receive
Useful headers:
• Accept and Content-Type: used for content format negotiation
14

17. Content Negotiation

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
16

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
16

20. 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
16

21. Access Control

22. Verbs

23. HTTP Verbs
• More than GET and POST
• PUT and DELETE to update and delete in a RESTful service
• HEAD, OPTIONS and others also specified
GET Read
POST Create
In REST, we use:
PUT Update
DELETE Delete
19

24. Service

25. Target Audience

26. Heartbeat

27. RPC Services

28. RPC: Remote Procedure Call
• Single endpoint
• Function name
• Parameters
• Return value
• SOAP is a kind of RPC
24

29. Soap

30. Data Formats

31. Small APIs

32. REST

33. 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
29

34. Design

35. Versioning

36. Consistency

37. Handling Errors

38. Delivery and Support

39. Web Service Design

40. Thanks!
https://joind.in/6385
@lornajane
http://lornajane.net/
36