Skip to main content

IPA-117: Documentation

Documentation serves as a primary tool for clients to better understand an API and its functionality. Consistent documentation patterns across the API platform will promote clarity, completeness and consistency.

State

Adopt

Guidance​

Descriptions​

  • API producers must provide descriptions for:
    • Properties
    • Operations
    • Parameters
    • Tags
  • API producers may provide descriptions for:
    • Schemas
  • Descriptions should be complete but brief
    • Descriptions should aim to cover
      • What it is
      • How to use it
      • Default values
      • Optional or required behavior
      • Common errors
    • Descriptions should avoid overly technical language
    • Descriptions must avoid company internal language conventions
    • Descriptions should prefer simple syntax that can easily be translated for non-English speakers
  • See Description Object
  • Documentation may link to external documentation when more in-depth information is pertinent

Description Formatting​

  • Description may use CommonMark
  • Descriptions must start with Uppercase and end with a full stop(.)
  • Descriptions must not use raw HTML
  • Descriptions should not include inline tables as this may not work well with all tools and in particular generated client code
    • Consider using lists over tables
    • Descriptions may contain CommonMark lists if the lists are short
    • If a comprehensive description with tables is needed, consider having a short description and using the externalDocumentation
  • Descriptions should not include inline links
    • If the API producer needs to provide links to external documentation, they should use the externalDocumentation

Examples​

  • API producers must provide a well-defined schema or example(s)
    • Tools can leverage schemas and field examples to generate request and response examples
    • For APIs where fields can be mutually exclusive, API producers should provide correct examples to consumers on how to use the API
    • For APIs that respond with plain text, for example, csv, API producers must provide an example
      • Some tools are not able to generate examples for such responses
  • See schema example

Default values​

Validation Keywords​

  • API producers must detail the required/optional nature of the field and any conditions in both responses and requests
  • For string values API producers may document:
    • minLength
    • maxLength
    • patterns, for example /^[a-zA-Z0-9][a-zA-Z0-9-]*$/
      • API producers should avoid overly specific patterns since changes to a pattern can be considered a breaking change
  • For numeric values API producers may document
  • For array fields API producers may document
  • API producers must not combine unrelated validation keywords
  • See validations for a full list of available validations

Operation Summary​

Operation summaries are titles describing an API operation.

  • Operation summaries must be concise
  • Operation summaries should describe what an operation does, but should not describe in-depths information about how to use it or nuances in behavior
    • For additional details about the behaviour of the operations, refer to Descriptions

Formatting​

  • Summaries must use Title Case
  • Summaries must not end with a period
  • Summaries must not use CommonMark

Language​

  • API Producers must use "One" when referring to a single item instead of "a" or "specified"
  • "Remove" vs. "Delete"
    • API Producers should use "Delete" when the operation is destroying a resource e.g. "Delete One Identity Provider"
    • API Producers should use "Remove" when the resource itself isn't being destroyed, e.g. "Remove One MongoDB Cloud User from One Project"
  • "Add" vs. "Create"
    • API Producers should use "Create" when the operation is creating a resource e.g. "Create One Identity Provider"
    • API Producers should use "Add" when the resource itself isn't being created, e.g. "Add One MongoDB Cloud User to One Project"
  • API Producers must not use abbreviations and technical formatting
    • "Line Items" instead of "lineItems"
    • "Organization Configuration" instead of "Org Config"
    • "Feature Compatibility Version" instead of "FCV"
  • API Producers must use "by" when referring to how something should be queried
    • "Return One Event by ID" instead of "Return One Event Using Its ID"
  • API Producers should avoid unnecessary filler words e.g. "possible", "available", "current"
  • API Producers must use "Return" instead of "Get" or "List"
    • API Producers must not use "Return All" unless the API can really return all items in a collection
      • Collections may contain an unbounded number of entries and must be paginated (see Pagination). If the total number of entries can exceed the page size and prevent the client from accessing the full set, do not use "all."
  • API Producers must use only one main action verb e.g. "Create," "Update," "Delete," "Add," "Remove"
  • API Producers must use "Update" instead of "Modify" or "Change"
  • API Producers must use "in" for actions operating within the parent (retrieving, updating, creating) and "from" for removing/disassociating
    • "Remove One MongoDB Cloud User from One Project" instead of "Remove One MongoDB Cloud User in One Project"
    • "Update One MongoDB Cloud User in One Project" instead of "Update One MongoDB Cloud User from One Project"

Further reading​