A presentation at WTFisSRE in in London, UK by Lorna Jane Mitchell
API Experience is Developer Experience Lorna Mitchell, Redocly @redocly ~ @lornajane
Postman State of the API report Top concern: 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
API style guides Covering style, compliance and other requirements Existing guidelines, can you pick one? •https://apistylebook.com/design/guidelines/ Create your own: •https://nordicapis.com/11-tips @redocly ~ @lornajane
Process and culture @redocly ~ @lornajane
Proposing API changes •Useful and timely feedback mechanisms •Consider user needs, and existing conventions •Think (very hard) about how things are named Design-first APIs @redocly ~ @lornajane
Automate for success Get tooling into CI/CD setup: •Use linting to check API fits standards •Create documentation previews •Spin up mock servers Encourage stakeholders to try the changed 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
OpenAPI linters •Programmatically check API description •Validate •Style checks •Ensure awesomeness @redocly ~ @lornajane
API documentation Docs are more than API reference! •Overview •Quickstart •Tutorials •Concepts @redocly ~ @lornajane
API documentation @redocly ~ @lornajane
Transform OpenAPI When your OpenAPI input isn’t complete enough for all it’s outputs, enhance it. Emerging tools: •OpenAPI overlays specification •Redocly decorators feature @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://apistylebook.com •https://github.com/APIs-guru/openapi-directory @redocly ~ @lornajane
Traditionally, best practice in API experience has been reserved for external APIs for paying customers. But as our systems grow in complexity, internal APIs are growing very quickly, and those best practices become very valuable within our organisations too. This session shares how having good processes in place throughout the API development lifecycle can improve the developer experience for both the people building and publish the APIs, and those integrating with them. Come and hear how to improve the quality and standards of APIs at your organisation, and how to choose tools to make the job easier. This session is recommended for anyone who needs to enable developer teams to play nicely together.
