Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST API Best Practices

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