Designing and Implementing REST APIs for the Long Haul

@schneidenbach Designing and Building REST APIs For the Long Haul
Spencer Schneidenbach

@schneidenbach

@schneidenbach More questions than answers

@schneidenbach

@schneidenbach API Design is Hard

@schneidenbach

@schneidenbach API Design is UX for Developers

@schneidenbach API Design is Important

@schneidenbach “Long Haul”

@schneidenbach –Kirsten Hunter @synedra “If you don’t make usability a
priority, you’ll never have to worry about scalability.”

@schneidenbach REST

@schneidenbach Representational State Transfer

@schneidenbach Uniform Interface Code on Demand (optional) Layered Stateless Cacheable
Client-Server The Six Constraints of REST

@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

@schneidenbach What IS a REST API?

@schneidenbach RESTful API != Good API

@schneidenbach

@schneidenbach RESTful API != Good API

@schneidenbach

@schneidenbach “Build our own spec”

@schneidenbach Who/what/where/why/how

@schneidenbach Why/who/what/how/where

@schneidenbach Why/who/what/how/where Technology questions LAST!

@schneidenbach

@schneidenbach Why?

@schneidenbach Why? • Support of a SPA or mobile app?
• Internal use? • Integration?

@schneidenbach –https://dzone.com/articles/designing-a-usable-ﬂexible-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?”

@schneidenbach Who?

@schneidenbach Who? …will use it?

@schneidenbach Who? …will test it?

@schneidenbach

@schneidenbach Who? …will help it go from beta to prod?

@schneidenbach What?

@schneidenbach How/Where?

@schneidenbach Begin with the end in mind

@schneidenbach A few simple rules • Don’t be creative, be
predictable. • Be consistent. • Get the important stuﬀ right - don’t bikeshed on things that don’t matter

@schneidenbach Step 0 Start by designing the basic behaviors of
the whole API.

@schneidenbach Basic Considerations • Security (authentication and authorization) • Status
codes • Response format • Leaky abstractions • Error handling • Versioning

@schneidenbach Security

@schneidenbach Authentication Authorization

@schneidenbach Authentication

@schneidenbach OAuth Authorization: Bearer niuq39cqj39042q39q

@schneidenbach Basic Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

@schneidenbach API Key X-Application-Key: this-is-a-secret-header

@schneidenbach Federated?

@schneidenbach Authorization

@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

@schneidenbach This isn’t predictable Status Code: 403 Forbidden { "Error":{
"Message":"Authentication failed: Employee does not exist or an Invalid Employee" } }

@schneidenbach Verbs PATCH DELETE POST PUT GET

@schneidenbach Accept: application/json Format

@schneidenbach Accept: application/xml Format

@schneidenbach Nouns vs. verbs Basically, use plural nouns

@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

@schneidenbach POST /api/jobs/123/phases GET /api/jobs/123/phases/1

@schneidenbach POST /api/jobs/123/phases GET /api/jobs/123/phases/234

@schneidenbach Sorting/paging/ﬁltering

@schneidenbach Leaky abstractions

@schneidenbach Theory Annex Threshold Lilia

@schneidenbach Inactive Deleted Visible Retired

@schneidenbach Avoid letting your specific implementations leak if they are
hard to use or understand.

@schneidenbach Error Handling Errors are going to happen. How will
you and your API manage them?

@schneidenbach 400 Bad Request

@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." }

@schneidenbach General error guidelines • Be as consistent as possible
across your API. • Provide enough information for the caller to ﬁx 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.

@schneidenbach

@schneidenbach COME ^ TO THAT

@schneidenbach Versioning

@schneidenbach Versioning should be top of mind from the get
go

@schneidenbach Change Management

@schneidenbach Versioning strategies • Header • Query String • Accept
• Route

@schneidenbach Header X-Api-Version: 1.0

@schneidenbach Query string GET /api/jobs?api-version=1.0

@schneidenbach Accept Accept: application/json;v=1.0

@schneidenbach Route GET /api/v1/jobs

@schneidenbach

@schneidenbach Versioning > breaking changes

@schneidenbach v1

@schneidenbach v2

@schneidenbach v3

@schneidenbach

@schneidenbach Deprecation

@schneidenbach

@schneidenbach Other Considerations • Documentation • SLAs (uptime) • Performance
guarantees • Deployment • Maintenance

@schneidenbach

@schneidenbach https://www.twilio.com/docs/api/errors/30003

@schneidenbach

@schneidenbach DOCUMENTATION

@schneidenbach DOCUME NTATION

@schneidenbach An API lives and dies by its documentation.

@schneidenbach

@schneidenbach https://www.twilio.com/docs/api/errors/30003 A Great Example An Ok Example

@schneidenbach SLAs

@schneidenbach SLAs • Will your API have a guaranteed uptime?
• What is the impact of downtime?

@schneidenbach Performance

@schneidenbach Performance • Scaling up/scaling out? • Guaranteed response times?
• Do you even need to think about this?

@schneidenbach Deployment

@schneidenbach

@schneidenbach Utilize your tools

@schneidenbach

@schneidenbach Maintenance

@schneidenbach Versioning > breaking changes

@schneidenbach Fix bugs, but don’t break things

@schneidenbach

@schneidenbach Support

@schneidenbach

@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.

@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!

@schneidenbach Thank you!

Designing and Implementing REST APIs for the Lo...

Designing and Implementing REST APIs for the Long Haul

More Decks by Spencer Schneidenbach

Other Decks in Technology

Featured

Transcript