REST API Best Practices

by Michael Stowe @ APIStrat 2014 in Chicago

Transcript

1. l All contents Copyright © 2014, MuleSoft Inc. REST API Best Practices Mike Stowe @MuleDev @mikegstowe Last Updated: 9/24/2014
2. l All contents Copyright © 2014, MuleSoft Inc. Understand WHY you are building an API. #1
3. l All contents Copyright © 2014, MuleSoft Inc. Understand what TYPE of API you are building. #2
4. l All contents Copyright © 2014, MuleSoft Inc. Most APIs are NOT RESTful.
5. l All contents Copyright © 2014, MuleSoft Inc. List out the user FUNCTIONALITY of your API. #3
6. l All contents Copyright © 2014, MuleSoft Inc. •  Users: create, edit, reset password, delete •  Messages: create draft, send, receive, move, mark as read, mark as unread, flag, remove flag, delete
7. l All contents Copyright © 2014, MuleSoft Inc. Think LONG TERM… like 2-3 years down the road long term. #4
8. l All contents Copyright © 2014, MuleSoft Inc. 8 ...people are fairly good at short-term design, and usually awful at long-term design.” “ -Dr. Roy Fielding
9. l All contents Copyright © 2014, MuleSoft Inc. Define your API in a standard, but flexible spec. #5
10. l All contents Copyright © 2014, MuleSoft Inc. •  RAML •  IO Docs •  Swagger •  API Blueprint
11. l All contents Copyright © 2014, MuleSoft Inc. MOCK your API and get USER feedback. Repeat #5 and #6 as necessary. #6
12. l All contents Copyright © 2014, MuleSoft Inc. Code to the SPEC... And Don’t Deviate. #7
13. l All contents Copyright © 2014, MuleSoft Inc. 13 Hybrid Approach Design Development Continuous, fluid, changeable Static… No turns
14. l All contents Copyright © 2014, MuleSoft Inc. 14 The Agile Design Cycle
15. l All contents Copyright © 2014, MuleSoft Inc. Use NOUNS as resources. #8
16. l All contents Copyright © 2014, MuleSoft Inc. Use: /users     Not: /createUser     /getUser   /deleteUser  
17. l All contents Copyright © 2014, MuleSoft Inc. Adhere to CRUD. #9
18. l All contents Copyright © 2014, MuleSoft Inc. Create (POST)   Read (GET)     Update (PUT/  PATCH)   Delete (DELETE)  
19. l All contents Copyright © 2014, MuleSoft Inc. Use Hypermedia. #10
20. l All contents Copyright © 2014, MuleSoft Inc. •  HAL •  JSON-LD •  JSON API •  Siren
21. l All contents Copyright © 2014, MuleSoft Inc. {      "data"  :  {          "user":  {              "fname":"first",              "lname":"last"          }      },        "_links"  :  {          "edit":  {              "href"  :  "/api/user/id/1"          },          "message":  {              "href"  :  "/api/message/id/1/lname/last"          }      }   }   HAL
22. l All contents Copyright © 2014, MuleSoft Inc. Use JSON. #12
23. l All contents Copyright © 2014, MuleSoft Inc. Use Authentication and Throttling. #13
24. l All contents Copyright © 2014, MuleSoft Inc. Use standard HTTP header codes in your responses. #14
25. l All contents Copyright © 2014, MuleSoft Inc. •  200 – OK •  201 – Created •  304 – Not modified •  400 – Bad Request •  401 – Not Authorized •  403 – Forbidden •  404 – Page/ Resource Not Found •  405 – Method Not Allowed •  500 – Internal Server Error
26. l All contents Copyright © 2014, MuleSoft Inc. •  418 – I’m a Teapot… •  420 – Enhance Your Calm Or if you’re feeling super creative…
27. l All contents Copyright © 2014, MuleSoft Inc. Use DESCRIPTIVE error messages. #15
28. l All contents Copyright © 2014, MuleSoft Inc. {      'exception'  {          'code'  :  'e3526',          'message'  :  'Missing  UserID',          'description'  :  'A  UserID  is  required  to  edit  a  user.',          'link'  :  'http://docs.mysite.com/errors/e3526/'      }   }   The more information you provide, the easier it will be for developers to integrate your API without contacting Support.
29. l All contents Copyright © 2014, MuleSoft Inc. Don’t break backwards compatibility… This means beware of versioning!!! #16
30. l All contents Copyright © 2014, MuleSoft Inc. Versioning is a necessary evil.
31. l All contents Copyright © 2014, MuleSoft Inc. Utilize a proxy (API Management System) #17
32. l All contents Copyright © 2014, MuleSoft Inc. Keep it simple. #18
33. l All contents Copyright © 2014, MuleSoft Inc. That means… Don’t get fancy. #19
34. l All contents Copyright © 2014, MuleSoft Inc. Because no matter how careful or clever you think are, you’re going to miss something… like this deck was missing #11
35. l All contents Copyright © 2014, MuleSoft Inc. view more @ www.mikestowe.com
36. l All contents Copyright © 2014, MuleSoft Inc. @MuleDev www.mulesoft.com