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

Designing and Implementing REST APIs for the Lo...

Designing and Implementing REST APIs for the Long Haul

REST APIs aren't dead - in fact they're more alive than ever. Don't let the hype around GraphQL put you off - RESTful APIs are being built and used by developers all over the world and that isn't changing anytime soon.

Before you start with File > New Project, however, there are some key decisions to be made about your API. Who is the main consumer? How will you authenticate? Who will own the documentation? How will you test it? How will you deploy it?

In other words, how will you manage the (probably very long) lifecycle of your REST API?

Join Spencer as he walks you through some of the decision making processes that you'll go through when building a REST API from the ground up. He'll offer advice as a designer of REST APIs of all shapes and sizes, for many different kinds of consumers, and share some of the many lessons learned over the years. Finally, we'll walk through some of the technical considerations you'll make when your developers finally sit down and start developing your API.

Spencer Schneidenbach

July 18, 2019
Tweet

More Decks by Spencer Schneidenbach

Other Decks in Technology

Transcript

  1. @schneidenbach –Kirsten Hunter @synedra “If you don’t make usability a

    priority, you’ll never have to worry about scalability.”
  2. @schneidenbach Resource identification Uniform Interface constraint Content-Type: application/json Resource manipulation

    with representations Self-descriptive Hypermedia as the engine of application state (HATEOAS) GET /employees/1234 PUT /employees/1234
  3. @schneidenbach Why? • Support of a SPA or mobile app?

    • Internal use? • Integration?
  4. @schneidenbach –https://dzone.com/articles/designing-a-usable-flexible-long-lasting-api “If you don't understand what it is you're

    building, why you're building it, or who you're building it for — how can it truly meet their needs? How can it meet your needs? How can it be successful?”
  5. @schneidenbach A few simple rules • Don’t be creative, be

    predictable. • Be consistent. • Get the important stuff right - don’t bikeshed on things that don’t matter
  6. @schneidenbach Basic Considerations • Security (authentication and authorization) • Status

    codes • Response format • Leaky abstractions • Error handling • Versioning
  7. @schneidenbach Status Codes 403 Forbidden (aka you can’t do that)

    401 Unauthorized (aka not authenticated) 404 Not Found 400 Bad Request 201 Created 200 OK
  8. @schneidenbach This isn’t predictable Status Code: 403 Forbidden { "Error":{

    "Message":"Authentication failed: Employee does not exist or an Invalid Employee" } }
  9. @schneidenbach { "invoices": [ { ... }, { ... }

    ] } GET /customers/1234/invoices GET /customers/1234 ?expand=invoices Within the parent object Sub-resource strategies As a separate request Using an expand parameter
  10. @schneidenbach Error reporting { "name": "Aviron Software" } Requires name

    and state POST /vendors 400 Bad Request Content-Type: application/json "State is required." { "firstName": "Spencer" } Requires first and last name POST /employees 400 Bad Request Content-Type: application/json { "errorMessage": "Your request was invalid." }
  11. @schneidenbach General error guidelines • Be as consistent as possible

    across your API. • Provide enough information for the caller to fix the issue with the least number of requests… mainly for their convenience. • Log requests and responses in their entirety and return a Request ID with the response for support.
  12. @schneidenbach Support guidelines • More GOOD documentation may mean less

    support • You must provide a means for people to ask for help • Make their jobs as consumers as easy as possible.
  13. @schneidenbach Remember these things • Think a little up front

    before File -> New Project. • Design a consistent “spec” for how your REST API will behave. • CONFORM TO THAT SPEC. COMMUNICATE WHEN YOU DON’T. • Remember good documentation and support!