= 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.
=== Design ===
==== 1. Check API catalog* ====
To ensure we are consistent and [[:en:Don't_repeat_yourself|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
* [[wikitech:API_Gateway#How_to_design_your_API|How to design your API (wikitech - wikimedia.org)]]
* [[mw:API:Etiquette|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.
* [https://docs.google.com/document/d/1G4T_5p2oT3dwVaLu8DvmWoyBgcoDO0kerq3gyd6LiJY/edit?usp=sharing API Description Google Doc Template]
* Example: [https://docs.google.com/document/d/1hvLD8kbo5omekPPrUbXP7kFKCozahRmdvR-ehQJMvM4/edit?usp=sharing 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.
=== Develop ===
==== 6. Develop against API description ====
* [https://github.com/wikimedia/service-template-node Service Template Node]
==== 7. Deploy your web service ====
==== 8. Add API route to the API gateway ====
* [[wikitech:API_Gateway#How_to_add_an_API_route|How to add an API route (wikitech - wikimedia.org)]]
=== Promote ===
=== Evaluate ===
=== Sunset ===
== Appendix:Terms ==
=== 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:
This site is not affiliated with or endorsed in any way by the Wikimedia Foundation or any of its affiliates. In fact, we fucking despise them.
|
