Best Practice in API Design
About This Talk  • The sum of my experiences      • Building APIs      • Consuming APIs      • Maintaining my own APIs  • ...
When To Use An APITimes you want to build an API:  • To share data to another app  • To give users better control/access t...
Web
Service
Design
Web
Request and Response
Statelessness
Status Codes
Status CodesWin/Fail indicator                     11
Status CodesWin/Fail indicator Common codes:                      200   OK                      302   Found               ...
Headers
HTTP HeadersHeaders are the metadata about the content we send/receiveUseful headers:  • Accept and Content-Type: used for...
Verbs
HTTP Verbs  • More than GET and POST  • PUT and DELETE to update and delete in a RESTful service  • HEAD, OPTIONS and othe...
Service
RPC Services
RPC: Remote Procedure Call • Single endpoint • Function name • Parameters • Return value                             18
RPC Services • XML-RPC • JSON-RPC • Soap               19
RPC Services • XML-RPC • JSON-RPC • Soap • other loose RPC services                              19
JSON vs XML vs ?
JSON • JavaScript Object Notation • Lightweight • Ideal for devices • Native in many languages • Great for AJAX applicatio...
XML • EXtensible Markup Lanugage • Verbose and precise • Best option for machine-to-machine                               ...
Soap
REST
RESTful Services • REpresentational State Transfer • URLs are unique resource identifiers • HTTP verbs indicate which opera...
Design
Target Audience
Statelessness
Version Parameter
Status Codes
Consistency
Small APIs
Heartbeat
Handling Errors
Content Negotiation
Access Control
Access Control            Do Not Reinvent the Wheel • Username/password • SSL • Tokens • OpenID/SAML/LDAP                 ...
Delivery and Support
Web Service Design
Thanks!          http://joind.in/3387               @lornajane          http://lornajane.net/                             ...
Upcoming SlideShare
Loading in …5
×

Best Practice in Web Service Design

5,434 views

Published on

API Design talk from the php|tek conference in Chicago, IL

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,434
On SlideShare
0
From Embeds
0
Number of Embeds
1,422
Actions
Shares
0
Downloads
53
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Best Practice in Web Service Design

  1. 1. Best Practice in API Design
  2. 2. About This Talk • The sum of my experiences • Building APIs • Consuming APIs • Maintaining my own APIs • Contains: • HTTP theory • Service types and data formats • Design pointers 2
  3. 3. When To Use An APITimes you want to build an API: • To share data to another app • To give users better control/access to their data • To build a modular, scalable system 3
  4. 4. Web
  5. 5. Service
  6. 6. Design
  7. 7. Web
  8. 8. Request and Response
  9. 9. Statelessness
  10. 10. Status Codes
  11. 11. Status CodesWin/Fail indicator 11
  12. 12. Status CodesWin/Fail indicator Common codes: 200 OK 302 Found 301 Moved 401 Not Authorised 403 Forbidden 404 Not Found 500 Internal Server Error 11
  13. 13. Headers
  14. 14. HTTP HeadersHeaders are the metadata about the content we send/receiveUseful 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 13
  15. 15. Verbs
  16. 16. 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 CreateIn REST, we use: PUT Update DELETE Delete 15
  17. 17. Service
  18. 18. RPC Services
  19. 19. RPC: Remote Procedure Call • Single endpoint • Function name • Parameters • Return value 18
  20. 20. RPC Services • XML-RPC • JSON-RPC • Soap 19
  21. 21. RPC Services • XML-RPC • JSON-RPC • Soap • other loose RPC services 19
  22. 22. JSON vs XML vs ?
  23. 23. JSON • JavaScript Object Notation • Lightweight • Ideal for devices • Native in many languages • Great for AJAX applications 21
  24. 24. XML • EXtensible Markup Lanugage • Verbose and precise • Best option for machine-to-machine 22
  25. 25. Soap
  26. 26. REST
  27. 27. 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 25
  28. 28. Design
  29. 29. Target Audience
  30. 30. Statelessness
  31. 31. Version Parameter
  32. 32. Status Codes
  33. 33. Consistency
  34. 34. Small APIs
  35. 35. Heartbeat
  36. 36. Handling Errors
  37. 37. Content Negotiation
  38. 38. Access Control
  39. 39. Access Control Do Not Reinvent the Wheel • Username/password • SSL • Tokens • OpenID/SAML/LDAP 37
  40. 40. Delivery and Support
  41. 41. Web Service Design
  42. 42. Thanks! http://joind.in/3387 @lornajane http://lornajane.net/ 40

×