API guidelines

🚧  Work in progress
This page is a draft. The information on this page is currently in development.

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.

About the API guidelines

These guidelines 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.

These guidelines are not absolute requirements. Not all existing WMF APIs comply with these guidelines. In fact, it is likely that every 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 questions or feedback, please leave a comment on the discussion page.

Terminology

• 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 of 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 specification standards include 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 service-level objective (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 without 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 rate limit 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, Meta-Wiki is the entity that handles authorization requests from clients

Design principles

Hosting and infrastructure

This section describes hosting and infrastructure guidelines for WMF-hosted services as well as externally hosted services integrated with WMF infrastructure.

Authentication and authorization

While write requests to api.wikimedia.org (POST, PUT, and DELETE methods) require an OAuth 2.0 token, the API Gateway does not currently support authorizing users and permissions.

Large datasets

This section describes guidelines for large datasets, both in request and response.

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.

*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.

• Wikimedia API Guidelines
• How to design your API (wikitech - wikimedia.org)
• Action API: Etiquette

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.

• API Description Google Doc Template
• Example: Topic Curation API Description
• Some thoughts on designing APIs

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

• Service Template Node
• To generate your API OpenAPI specification file as you are developing, you can install the npm package servicelib-node-spec to your project and follow its instructions to first annotate your routes, allowing you to automatically generate your API specification file.

8. Add API route to the API gateway

• How to add an API route (wikitech - wikimedia.org)

We recommend you start off with first adding your API to the staging instance of the API gateway before production.

Deploy

Experimental

Promote

prod vs beta gateway

REST API Guidelines

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.

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