User:DKinzler (WMF)/API Guidelines: Difference between revisions

• 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-docsExisting 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
• 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
• 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/

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
    • 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 field (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?
  • 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 (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