A presentation at PHP[TEK] in in Atlanta, GA, USA by Lorna Jane Mitchell
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
We’ve all heard about ‘API First’ when it comes to building a new product or feature. It can allow your team to develop in parallel, enable expansion to multiple platforms, and create an opportunity for outside integration.
But creating a usable and maintainable API doesn’t start with opening your IDE. If you want to build an API that will meet the long term needs of your users (both internal and external), you start by designing the interface they’ll consume, not writing the code that powers that interface.
In this session, we’ll consider the benefits of a design-first approach, how that contrasts some of our natural instincts as web developers, and how design-first works even when you don’t do ‘API first’.
