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

• API Guidelines | Product Brief

For Maintainers

• 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
• 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
• meta:User:BPirkle (WMF)/Stuff/Designing APIs
• "Good API, Great API" Google Doc
• Authorization and Rate Limiting: https://docs.google.com/document/d/1pG2qd4w_RW7wl_6Od1jFo4CkKA3zCA2wQDtmY2e5Tb8/edit#
• API:Cross-site requests
• Ideas:
  • paging?
  • localization (mostly for errors)
• Writing an extension for deployment
• Wikimedia services policy (see also Requests for comment/Standards for external services)
• Requests for comment/API roadmap
• Micosoft API Guidelines, Microsoft API Versioning
• Google API Guidelines (these seem pretty good!)
• 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

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
• API Description Template
• API Platform Model
• Wikimedia API Guidelines
• Wikimedia Foundation API Principles

Bill's Links

• https://cloud.google.com/apis/design
• https://opensource.zalando.com/restful-api-guidelines/index.html#table-of-contents
• https://meta.stoplight.io/docs/platform/52ab0a117eadd-welcome-to-the-stoplight-docs
• 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

Search / WDQS

• https://wikitech.wikimedia.org/wiki/Search/Technical_interactions
• https://wikitech.wikimedia.org/wiki/Wikidata_Query_Service/Technical_interactions

Bits & Pieces

Note to self: looked at: Adidas, Maturity, Atlassian, Whitehouse, Google

Typical Structure & Aspects

• Documentation
  • discoverable specs and schemas
• 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
  • use of error codes, body of error responses
  • content types & negotiation
  • caching
  • conditionals
  • redirects (normalization, deprecation, and other)
  • 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
• payload data
  • serialization (JSON)
  • shared data model
  • standard data types (date format, language codes, etc)
  • standard field names (rel, ref, etc) - compare https://cloud.google.com/apis/design/standard_fields?hl=en
  • schemas
  • pagination, ordering, filtering
  • response for long running operations?
  • standard query params: localization, variants, embedding/expansion
  • batch operations and collections (put vs post)
  • foreign key relation (entitiy 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
• Evolution
  • Versioning
  • URL vs headers, etc
  • content negotiation
  • deprecation
  • compatibility, see https://cloud.google.com/apis/design/compatibility?hl=en
• URL structure
  • characters & encoding
  • resources & collections (sub-collections, formats, nested resources, etc)
  • use American English nouns (singlular or plural?) (kebab-case or CamelCase?)
  • searching vs. listing
  • formats / file extension suffix
• 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)