User:SKim (WMF)/API Guidelines

= API Guidelines = This is a work in progress

API Lifecycle
This document highlights the suggested process in which one should follow from idea to deployment to deprecation of a web API.

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

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

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.

6. Develop against API description

 * Service Template Node

8. Add API route to the API gateway

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

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.

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 stability 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

API Stability

 * Experimental: The API description could change at anytime without any future notice.
 * Stable:
 * Deprecated: