User:BPirkle (WMF)/Stuff/Designing APIs

From Meta, a Wikimedia project coordination wiki

The following came from https://phabricator.wikimedia.org/T288127. This probably isn't the right home for it, but this at least gets it on-wiki while we figure out the right place.

Steps to Design an API, from initial concept to creating a formal technical spec.

  1. Think about what you're trying to accomplish. An API is probably the right choice, but consider other possibilities. Some applications use shared files, shared storage, etc.
  2. Think about who will be using your API. Think about their technical preferences and proficiencies, and what other APIs they may already be accessing. Consider things like API type (REST/RPC/GraphQL/etc), how authentication is handled (OAuth/tokens/etc), how sophisticated the client may be in terms of things like caching headers, translations, etc. This may involve conversations with multiple people.
  3. Think about who will be implementing the API (just you? other developers on your team? someone else?). Think about their technical preferences and proficiencies, and what other APIs they may already be familiar with creating. Apply the same considerations as in #2. This may involve conversations with multiple people.
  4. Think about technical constraints surrounding the API and its anticipated usage. Does it have characteristics more suited to one technology or another? REST is extremely popular, and is often the right answer. But suppose your API will be used in a very bandwidth-sensitive situation where overfetching is a major concern. Maybe GraphQL would be better.
  5. Combine #2, #3, and #4, and see how well they match. Hopefully they all lead to the same answer. But if not, step back and resolve any mismatches. This may involve even more conversations. At the end of this step, you haven't even defined any endpoints. But you have chosen appropriate technologies, and should have a sense of how both producers and consumers expect them to be used in the context of this API.
  6. Consider how to model whatever is being accessed in whatever technology you decided on. For example, if you chose REST, define the resources your API will expose, which can be treated as collections, how you'll identify resources (id vs name), how you'll handle relationships between resources, etc.
  7. Consider how your API will handle things that actively affect endpoint design. This includes things like filtering, sorting, and pagination
  8. Consider how your API will handle things that don't actively affect endpoint design (or at least affect it tangentially). This includes things like rate limiting, authentication, and caching.
  9. Actually define your endpoints, preferably in a standard format that can be easily shared with others (ex. OpenAPI).
  10. Iterate and refine as necessary
Retrieved from "https://meta.wikimedia.org/w/index.php?title=User:BPirkle_(WMF)/Stuff/Designing_APIs&oldid=22396942"