User:DKinzler (WMF)/API Guidelines

API Guidelines | Product Brief

Resources

REST 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-s hould-use-links-not-keys-to-represent-relationships-in-apis?hl=en

Existing Wikimedia Resources

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

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)
- 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
  - 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)
  - https://opensource.zalando.com/restful-api-guidelines/index.html#data-formats
- 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
  - 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?
    - 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
  - (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 (plural for collections) (kebab-case)
  - https://stackoverflow.com/questions/6845772/should-i-use-singular-or-plural-name-convention-for-rest-resources
  - https://blog.dreamfactory.com/best-practices-for-naming-rest-api-endpoints/
- 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

Guidance needed

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