A presentation at Appdevcon - Endpointcon in in Amsterdam, Netherlands by Lorna Jane Mitchell
API Governance without tears Lorna Mitchell, Redocly @redocly ~ @lornajane
API governance Good API governance is invisible Without it: •designing changes is more difficult •changes get rejected and need repeat work •APIs become inconsistent •more difficult to adopt an API @redocly ~ @lornajane
Start with standards @redocly ~ @lornajane
Hypertext links HAL: Hypertext Application Language https://en.wikipedia.org/wiki/Hypertext_Application_Language { “_links”: { “self”: { “href”: “http://example.com/api/book/hal-cookbook” } }, “id”: “hal-cookbook”, “name”: “HAL Cookbook” } Common for pagination, and nested data resources @redocly ~ @lornajane
Problem details RFC7807 https://datatracker.ietf.org/doc/html/rfc7807 { “type”: “https://example.com/probs/out-of-credit”, “title”: “You do not have enough credit.”, “detail”: “Your current balance is 30, but that costs 50.”, “instance”: “/account/12345/msgs/abc”, “balance”: 30, “accounts”: [“/account/12345”, “/account/67890”] } Common body format with error responses @redocly ~ @lornajane
Authentication Adopt an existing standard •OAuth2 •JWT •access token / API key •basic authentication Use 401: Unauthorized @redocly ~ @lornajane and 403: Forbidden appropriately
OpenAPI Machine-readable API description https://openapis.org @redocly ~ @lornajane
OpenAPI structure openapi: 3.1.0 info: servers: [ https://example.com ] paths: “/events”: post: operationId: createEvent responses: 200: get: operationId: listEvent responses: 200: components: schemas: event: {} @redocly ~ @lornajane // (this example is not to scale)
Design good governance Start with an existing ruleset @redocly ~ @lornajane
Designing rulesets Rules for compliance •Every endpoint must have security defined •Contact information for API owner •Headers required for all endpoints •License information provided Pull request workflow provides an audit @redocly ~ @lornajane
Designing rulesets Rules for happy engineers •Operation IDs must be unique •Every operation has an error response •Paths cannot be ambiguous paths: “/user/{name}”: … “/{team}/admin_user”: … @redocly ~ @lornajane
Designing rulesets A matter of taste •Use plurals in path segments •Standardise on case (kebab-case or camelCase) •No trailing slashes in paths @redocly ~ @lornajane
Designing rulesets Rules for developer delight •Tags should have descriptions •Parameters must have descriptions and examples parameters: - in: query name: userId description: | User ID, returned by the listUser endpoints. (tip: find your own user ID by calling /user/me) schema: type: string example: “U0123”
@redocly ~ @lornajane
Non-lintable standards The machines cannot do everything * Humans must review changes too •would you want to use this API? •is the naming sensible and intuitive? •is the change consistent with the existing API? * Try asking an AI “does this naming make sense?” @redocly ~ @lornajane
API change management API governance: it’s a practice, not a job title @redocly ~ @lornajane
Design-first APIs Change the OpenAPI files only, open a pull request Then, use CI to: •publish docs •spin up a mock server •check it meets the standards •get humans to do their review @redocly ~ @lornajane
Tools for API Governance 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 @redocly ~ @lornajane
Improve API experience •Publish the OpenAPI •Add more examples to your API descriptions •Use writers to improve the words and descriptions •Add metadata to help code generators •Use a design-first, code-style workflow @redocly ~ @lornajane
Good API governance (without tears) @redocly ~ @lornajane
Resources •https://lornajane.net •https://redocly.com •https://apistylebook.com •https://openapi.tools •https://github.com/APIs-guru/openapi-directory •https://apisyouwonthate.com @redocly ~ @lornajane
