THIS PAGE IS IN PROGRESS AND IS NOT YET READY TO BE RELIED UPON

General

Introduction

This document describes guidelines and recommendations for creating APIs at and for use with the Wikimedia Foundation and its associated data, infrastructure, applications, and services.

What these guidelines are

These guidelines are an attempt to create consistency and encourage secure, efficient, and maintainable APIs. They draw upon previous guidelines and design principles at WMF, as well as common practice across the broader technical community.

What these guidelines are not

These guidelines are not absolute requirements. Not all existing WMF APIs comply with these guidelines. In fact, it is likely that every non-trivial WMF API differs from these guidelines in some respect. It is equally likely that future WMF APIs will deviate from them. However, any such deviations should be purposeful. In other words, WMF APIs should follow these guidelines unless they have good reason not to.

These guidelines are not comprehensive. There are many aspects to creating real-world APIs, and it is not reasonable for any one document to cover every situation that may arise.

These guidelines are not permanent or unchangeable. If you find something you disagree with herein, or find something missing for which you have a suggestion, please suggest improvements.

Terms Used

  • API (disambiguation)
    • API (Offering): The branded offering for data access in the global context.
    • API (SaaS): A web service that provides a capability in the context within Wikimedia.
    • API (Interface): The client-facing component that interprets HTTP requests
  • API Specification (API Spec)
    • A technical standard, like OpenAPI 3.0, that defines how to describe an API’s interface in a general, broadly applicable way that is both machine-parsable and human-readable. Other API specifications are GraphQL and AsyncAPI.
  • API Description
    • A file articulating a single API’s interface that fulfills the requirements and expectations of an API specification.
  • API Documentation
    • The collection of things necessary to convey sufficient meaning so that clients can successfully use the deployed API through the interface. This includes, but is not limited to, the API Description.
  • Prototype API
    • A deployed web service with the purpose of being tested as an experiment. These APIs do not have a defined SLO nor are able to accept public requests higher than a certain threshold rate-limit. They have an API status of "experimental" and could change at anytime with no notice. +Included in using the API Gateway
  • Production API
    • A deployed web service that has been validated as a prototype and ready for wider use. Has a specified ratelimit through the API Gateway
  • End-User
    • The human on their phone pushing buttons on the their respective application
  • Client Web App
    • The web application that serves as an interface for the end-user and is the entity making requests to API web service(s)
  • Authorization Server
    • For API web services at the foundation, metawiki is the entity that handles authorization requests from clients

Design Principles

Hosting and Infrastructure

this section will mostly be for WMF-hosted services but maybe there are things to say about externally hosted things working with our infra?

Authentication and Authorization

The API Gateway does not currently support authenticating requests nor does it support authorizing users and permissions.

caching

rate limiting

long running tasks

large data sets, either in request or response

etc

API Lifecycle

Design Phase

1. Check API catalog*

To ensure we are consistent and DRY, exploring through the existing catalog of APIs will help find reusable patterns or APIs you can extend from.

*This currently does not exist yet, please see our List of APIs which is not guaranteed to be up to date

2. Check API guidelines

The evolving set of API guidelines provides the standards and rules we suggest for all API producers to follow.

3. Create API description

Before doing any coding, ensure you have a clear idea and agreement on what your API is supposed to look like. Using the template below will also allow for others to leave comments as well as keep a change log.

4. Generate reference documentation

Based on your API description that you’ve drafted, you can now generate your reference documentation.

5. Get feedback

Whether you’re designing an API for internal operations or for external partners to leverage, you should get feedback from your users before starting any development on your API.

Develop

6. Develop against API description

7. Deploy your web service

8. Add API route to the API gateway

Deploy

Experimental

Promote

prod vs beta gateway

Evaluate

Sunset

REST API Guidelines

HTTP

Methods

Headers

Status Codes

Naming

we should pick singular vs plural but mention it is just a recommendation

OpenAPI

explain what it is good for in our infrastructure

maybe include some lessons from RESTBase and how Kask avoided those issues. See Eric's OpenAPI thoughts (and its talk page) for more.

service runner / x-amples?

API Catalog

auto-generation via code annotations

use as communications/contract across teams

Errors

general recommendations on error handling

Logging/Monitoring

does this get its own section or can it go under errors? are these related enough to be one section, or should they be separate?

Other API Types

Explain that we haven't done that yet, but included this just to make it clear that other API types are not prohibited and we'll fill this in when we get there

Related Links

links to all our other docs that prolly contradict this one...