Design First is Better than API First

Design-First is better than API-First Lorna Mitchell, Nexmo

It all begins with a story

UX Informs API Decisions All users have context, and this informs: • Style: REST, RPC, something else? • Format(s): JSON or XML (or a binary format …) • Authentication: pick a standard, e.g. OAuth • Error behaviour: application/problem+json • Collections: filtering, pagination • Hypermedia @lornajane

Write Decisions Down All stakeholders can access and contribute to documentation. @lornajane

Design Decisions There is no “right” answer, but BE CONSISTENT @lornajane

API Styles Most modern APIs are RESTful HTTP APIs. Also consider: • RPC APIs • Asynchronous APIs • Webhooks @lornajane

Data Formats Consider supporting more than one format. Don’t forget input formats as well as outputs! JSON XML { <message> Hello World </message> “message”: “Hello World” } @lornajane

Authentication Pick a standard, any standard! I prefer token-based schemes such as OAuth or JWT because: • they can be limited in scope or time • individual tokens can be revoked without affecting other tokens’ access @lornajane

Error Behaviour Must haves: • Consistent behaviour on all endpoints • Status code indicates success/fail • Data structure is predictable Nice to haves: • Link to further information • Use existing standard e.g. RFC 8707 https://tools.ietf.org/html/rfc7807 @lornajane

NAMING THINGS IS HARD Get feedback on naming for everything from everyone, all the time Be consistent! @lornajane

Designing Endpoints for REST • Is this a resource or a collection? • Which verbs make sense for this resource? • Is this collection something we nest inside the resource, or a separate collection? • /users/123 could nest all the user’s blog posts in a field • /users/123/posts as a separate to fetch all those posts • /posts?user_id=123 is also an option … then be consistent across the whole API @lornajane

Choosing Collaboration Tools @lornajane

Documentation Tools The best ones: • Work well with source control • Are quick to create documentation • Are easy to deploy • Are painless to maintain/update @lornajane

API Description Languages (this is a whole other talk) Description languages like OpenAPI make a machine-readable description of your API • It can be used to generate documentation • It can be used to fire up a mock server to play with • It can be used to import a collection into Postman • It can generate the basic outline of either the API server itself, or a client @lornajane

Best API Docs • Include a Quickstart for API-ready individuals • Include detailed tutorials for those who want them • Have detailed API reference materials Every API is someone’s first API @lornajane

The Impact of Design-First @lornajane

Consistency is key Implementation is a detail @lornajane

Resources • PHP Web Services (O’Reilly) • RESTful Web APIs (O’Reilly) • https://www.openapis.org • https://lornajane.net • https://benramsey.com • https://apievangelist.com @lornajane