User:DKinzler (WMF)/API Guidelines


 * API Guidelines | Product Brief

Resources
REST best practice


 * Microsoft API Versioning
 * https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
 * Maturity model, see also https://blog.restcase.com/4-maturity-levels-of-rest-api-design/
 * List of other people's API Guidelines: https://github.com/masteringapi/rest-api-standards
 * https://masteringbackend.com/posts/api-design-best-practices
 * https://phabricator.wikimedia.org/T332212 Major (API) versioning of Event Platform streams
 * meta:User:BPirkle (WMF)/Stuff/Designing APIs
 * "Good API, Great API" Google Doc
 * https://meta.stoplight.io/docs/platform/52ab0a117eadd-welcome-to-the-stoplight-docs Existing Wikimedia Resources


 * https://docs.google.com/spreadsheets/d/174pZRPhdL9bMec-87Eho8HB5kV7Ua14fyrxuxoENoh4/edit#gid=1711717114
 * https://docs.google.com/document/d/1h_nvjACYnvqrq93REnubafGckRXqUga3N56bPBPcn9k/edit?pli=1#heading=h.w29abfmznz7v
 * API Description Template
 * API Platform Model
 * Wikimedia API Guidelines
 * Wikimedia Foundation API Principles
 * Writing an extension for deployment
 * Wikimedia services policy (see also Requests for comment/Standards for external services)
 * Requests for comment/API roadmap
 * Authorization and Rate Limiting: https://docs.google.com/document/d/1pG2qd4w_RW7wl_6Od1jFo4CkKA3zCA2wQDtmY2e5Tb8/edit#
 * API:Cross-site requests
 * API Life Cycle (draft by Daniel)
 * API versioning
 * https://phabricator.wikimedia.org/T232485 REST Versioning RFC
 * Service-template-node/APIDesign
 * https://api.wikimedia.org/wiki/Community/API_guidelines
 * API_Gateway
 * Wikimedia_Engineering_Architecture_Principles
 * Core Platform Team/Initiative/Core REST API in Mediawiki/Design principles
 * https://wikitech.wikimedia.org/wiki/Services/FirstDeployment
 * https://wikitech.wikimedia.org/wiki/ServiceOwnership
 * https://wikitech.wikimedia.org/wiki/Deployment_pipeline
 * https://github.com/wikimedia/service-template-node


 * https://wikitech.wikimedia.org/wiki/Search/Technical_interactions
 * https://wikitech.wikimedia.org/wiki/Wikidata_Query_Service/Technical_interactions
 * REST vs RPC: https://www.smashingmagazine.com/2016/09/understanding-rest-and-rpc-for-http-apis/

Other Org's API Guidelines


 * [x] Stripe https://stripe.com/docs/api
 * [x] Zalando https://opensource.zalando.com/restful-api-guidelines/index.html#table-of-contents
 * [x] Adidas https://github.com/adidas/api-guidelines/tree/master/rest-api-guidelines
 * [x] Atlassian https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/
 * [x] Google https://cloud.google.com/apis/design?hl=en
 * [x] Heroku https://github.com/interagent/http-api-design
 * [x] Microsoft https://github.com/microsoft/api-guidelines
 * [x] The White House https://github.com/WhiteHouse/api-standards
 * [ ] Kubernetes https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning
 * [ ] SBB https://schweizerischebundesbahnen.github.io/api-principles/restful/best-practices/

For Clients
 * API Life Cycle -> stable interface
 * https://meta.wikimedia.org/wiki/User-Agent_policy
 * API:Etiquette
 * https://api.wikimedia.org/wiki/Documentation/Best_practices
 * https://foundation.wikimedia.org/wiki/Terms_of_Use/en
 * Manual:Creating a bot
 * en:Wikipedia:Bot_policy
 * RESTbase Swagger UI https://en.wikipedia.org/api/rest_v1/
 * Wikidata Data access best practices
 * https://medium.com/capital-one-tech/3-best-practices-for-api-clients-feef9ec97f1a

Bits & Pieces
Note to self: looked at: Adidas, Maturity, Atlassian, Whitehouse, Google, Microsoft, Heroku, Zalando, Atlassian, Stripe.

Typical Structure & Aspects


 * Geenral:
 * when NOT to use REST
 * REST vs RPC: https://www.smashingmagazine.com/2016/09/understanding-rest-and-rpc-for-http-apis/
 * RPC: plain old form vs. JSON RPC vs SOAP.
 * Scope: where does this apply? (only wmf prod? what about toolforge? cloud services?)
 * only applies to new APIs, existing APIs SHOULD adopt it over time.


 * Documentation
 * discoverable specs and schemas
 * gateway root, e.g. en.wikipedia.org/api: list components (or swagger UI with selector of components and versions); also link ToS, Client Guidelines.
 * component root: list versions (or redirect to API root)
 * api root: return OpenAPI spec (or redirect sto swagegr UI, based on content negotiation); also link ToS, Client Guidelines.
 * maybe: include full version in spec URL, redirect from api root
 * required additional meta-data in the spec:
 * stable/unstable
 * public/restricted
 * extra properties
 * expandable
 * pagination
 * HTTP binding
 * use of verbs, HATEOAS, idempotence (put vs post vs patch)
 * see https://cloud.google.com/apis/design/standard_methods?hl=en
 * see google's idea for custom verbs
 * changing collections https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#95-changing-collections
 * https://opensource.zalando.com/restful-api-guidelines/index.html#229
 * use of status codes https://opensource.zalando.com/restful-api-guidelines/index.html#150
 * body of error responses
 * rfc:7807
 * content types & negotiation
 * don't use content negotiation for breaking changes
 * use Vary header
 * localized responses
 * caching
 * https://opensource.zalando.com/restful-api-guidelines/index.html#227
 * conditionals
 * redirects (normalization, deprecation, and other)
 * content-type response header should reference spec (and version!)
 * version mismatch in accept header should trigger error response
 * other headers
 * guidance on urls vs header vs query param
 * resources vs entities
 * etags, see https://cloud.google.com/apis/design/design_patterns?hl=en#etags
 * multi-value headers and query params: https://opensource.zalando.com/restful-api-guidelines/index.html#154
 * payload data
 * Wikimedia_Engineering_Architecture_Principles
 * serialization (JSON)
 * shared data model
 * standard data types (date format, language codes, etc)
 * https://opensource.zalando.com/restful-api-guidelines/index.html#data-formats
 * standard field names (rel, ref, etc) - compare https://cloud.google.com/apis/design/standard_fields?hl=en
 * schemas
 * pagination, ordering, filtering
 * https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#98-pagination
 * https://opensource.zalando.com/restful-api-guidelines/index.html#227
 * meta-data and wrapper
 * lists and pagination (next/previous/first/last)
 * batches
 * rel (self, edit, delete, add, etc)
 * license
 * special field names (_warning or @warning or $warning?)
 * warning, schema, debug.
 * http-equiv?
 * response for long running operations?
 * standard query params:
 * localization, variants, flavor
 * debug
 * filter, limit, order, offset
 * embedding/expansion
 * https://opensource.zalando.com/restful-api-guidelines/index.html#137
 * https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/
 * https://stripe.com/docs/api/expanding_objects
 * batch operations and collections (put vs post)
 * relative vs absolute URL and URIs
 * foreign key relation (entitiy URIs)
 * resources URLs
 * domains and bounded contexts, separation of concerns
 * no data in keys (really? maps are neat...)
 * errors, compare https://cloud.google.com/apis/design/errors?hl=en
 * block info for 403!
 * rate limit info for 429!
 * Evolution
 * Versioning
 * URL vs headers, etc
 * (disagree) https://opensource.zalando.com/restful-api-guidelines/index.html#114
 * content negotiation
 * deprecation
 * Sunset and deprecation headers https://opensource.zalando.com/restful-api-guidelines/index.html#189
 * 308 redirects
 * clients: look for Sunset and Deprecation headers!
 * https://opensource.zalando.com/restful-api-guidelines/index.html#deprecation
 * https://kubernetes.io/docs/reference/using-api/deprecation-policy/
 * compatibility, see https://cloud.google.com/apis/design/compatibility?hl=en
 * versioning, see https://apisyouwonthate.com/blog/api-versioning-has-no-right-way/
 * URL structure
 * characters & encoding (slashes, colons, hashes, utf8, query params, etc)
 * resources & collections (sub-collections, formats, nested resources, etc)
 * nesting vs referense -> composition vs aggregation
 * use American English nouns (singlular or plural?) (kebab-case or CamelCase?)
 * searching vs. listing
 * formats / file extension suffix
 * no trailing slashes, no empty segments
 * extra verby as suffix?
 * compound ids?
 * Compliance
 * testing (pact)
 * SLA, rate limits
 * https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#143-retry-after-and-ratelimit-headers
 * Security
 * Authentication
 * CORS/CSP
 * CSRF
 * Design process (see also https://cloud.google.com/apis/design/resources?hl=en)
 * Model entities (resources, nouns) and their relationships
 * Design a URL scheme for addressing the resources and collections
 * Define schemas for representing the entities.
 * Determine the behavior of standard verbs for each resource (and collection)

Clients
 * How to discover APIs
 * Where to find documentation and specs
 * common data types
 * error formats
 * paging
 * Relevant HTTP standards
 * resilience
 * handling 5xx
 * Retry and back-off
 * Relevant REST best practices
 * What is stable / unstable
 * use the latest version
 * don't rely on undocumented behavior
 * Do not start using deprecated APIs
 * don't use restricted APIs
 * Follow the ToS
 * Surface Deprecation and Sunsetting
 * Follow 308
 * Be nice
 * Consider the cost
 * Follow 429 / Retry-After
 * Be careful with concurrency
 * React to blocks (403?)
 * Set User-Agent
 * When and how to use auth
 * use OAuth when acting on behalf of others
 * csrf