User:DKinzler (WMF)/API Guidelines
Resources
editREST best practice
- OData https://www.odata.org/
- 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
- https://cloud.google.com/blog/products/application-development/api-design-why-you-should-use-links-not-keys-to-represent-relationships-in-apis?hl=en
Existing Wikimedia Resources
- https://phabricator.wikimedia.org/T114384 Standardise procedures for deprecating public-facing code
- 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
- wikitech:API_Gateway#How_to_design_your_API
- Wikimedia_Engineering_Architecture_Principles#api/domain
- Core Platform Team/Initiative/Core REST API in Mediawiki/Design principles
- Wikimedia Product/Wikimedia Product Infrastructure team/API endpoint stability policy
- 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/
- [ ] OData https://www.odata.org/
- [ ] Slack https://slack.engineering/how-we-design-our-apis-at-slack/
- [ ] Wordpress https://developer.wordpress.org/rest-api/
- [ ] Stripe https://stripe.com/blog/api-versioning
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
- API:Client code/Gold standard
- API:Cross-site_requests
Bits & Pieces
editNote 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.
- when NOT to use REST
- 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
- discoverable specs and schemas
- HTTP binding
- use of verbs, HATEOAS, idempotence (put vs post vs patch)
- 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
- conditionals
- redirects (normalization, deprecation, and other)
- content-type response header should reference spec (and version?)
- version mismatch in accept header should trigger error response
- content negotiation may be used
- 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#api/domain
- serialization (JSON)
- shared data model
- standard data types (date format, language codes, etc)
- field names
- standard fields (rel, ref, *-url, etc) - compare https://cloud.google.com/apis/design/standard_fields?hl=en
- snake_case ascii identifier (prefix)?[a-z]+[a-z0-9]*(_[a-z]+[a-z0-9]*)
- schemas
- json, content-type
- pagination, ordering, filtering
- 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?
- rel link (sunset, etc) -> standard rel ref object
- response for long running operations?
- standard query params:
- localization, variants, flavor
- debug
- filter, limit, order, offset
- embedding/expansion
- 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
- 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 (plural for collections) (kebab-case)
- 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
- 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
Guidance needed
edit- REST vs Action, rpc endpoints in the REST framework
- component names and versions
- entity names, singlular vs plural, trailign slashes
- common wrappers for listings
- shared vocab of properties
- shared object schemas
- helper objects