API Experience is Developer Experience

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