API Experience is Developer Experience

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