A presentation at O’Reilly APIs: Possibilities and Pitfalls by Lorna Jane Mitchell
API Experience is Developer Experience Lorna Mitchell, Redocly @redocly ~ @lornajane
Postman State of the API report 2023 Top decision factor: how well an API integrates with internal apps and systems. https://www.postman.com/state-of-api/ @redocly ~ @lornajane
API project pre-requisites •API styles and governance •Versioning and deprecation policy •Change review process •Tools to support the lifecycle @redocly ~ @lornajane
Start with standards @redocly ~ @lornajane
OpenAPI descriptions A standard way to describe an API •JSON/YAML format •Endpoints and verbs •Parameters and schemas •Reuse elements with $ref •Responses, including error responses https://openapis.org @redocly ~ @lornajane
OpenAPI example openapi: 3.0.1 servers: - url: http://datasette.local - url: https://datasette.io info: description: Execute SQL queries against a Datasette database and return the results as JSON title: Datasette API version: v1 paths: /content.json: get: description: Accepts SQLite SQL query, returns JSON. Does not allow PRAGMA statements. Credit: https://github.com/APIs-guru/openapi-directory @redocly ~ @lornajane
Design API governance Start with an existing ruleset @redocly ~ @lornajane
Designing rulesets •Level 0: Is the document valid? •Level 1: Does it meet basic (compliance) standards? •Level 2: Is it consistent with the rest of the API? •Level 3: Is it a joy to work with? @redocly ~ @lornajane
Process matters @redocly ~ @lornajane
Proposing API changes Use a source control workflow •Useful and timely feedback mechanisms •Consider user needs, and existing conventions •Think (very hard) about how things are named @redocly ~ @lornajane
Automate for success •Use linting to check API fits guidelines •Create documentation previews •Spin up mock servers @redocly ~ @lornajane
API Council Bring key API contributors together for every review: •Would you want to use this API? •Is the naming sensible and intuitive? •Is the change consistent with the existing API? @redocly ~ @lornajane
API experience at scale @redocly ~ @lornajane
API catalog Central registry/marketplace/inventory •All APIs are registered here •OpenAPI descriptions •Establish documentation conventions •Team contact information •Standards/readiness @redocly ~ @lornajane
API catalog @redocly ~ @lornajane
API lifecycle tools tl;dr https://openapi.tools/ @redocly ~ @lornajane
API lifecycle tools •Linting, standard rulesets or make your own •Documentation, build a preview of proposed changes •Mock servers, try before you build •Extensions, improve an existing description •SDKs, improve developer onboarding @redocly ~ @lornajane
API Lifecycle DevX @redocly ~ @lornajane
Resources •https://lornajane.net •https://redocly.com •https://openapi.tools •https://www.postman.com/state-of-api/ •https://github.com/APIs-guru/openapi-directory @redocly ~ @lornajane
