API reference template

[maryamsulemani97]

closes #1351

Based on the feedback we got on this Slack thread, we'll go with format 3.

• The format is similar to Stripe

• We start by explaining the object returned
  • If it's a simple object (like indexes), we use a table
  • If it's a complex object (like keys), we use a header structure
• We next list all the endpoints
  • We don’t explain the fields returned for each endpoint but link the response to the object returned
  • This format goes against our H2=endpoint convention

For reviewing the PR:

• Go to the reference/api/format.md page
  • Link for deploy preview
• There are two objects used here, simple and complex. The purpose is to have a format for both types. The actual API reference will have one

To be discussed:

• List all endpoints:
  • Should we have query parameters and default values in ``?
  • Should the code sample use all query parameters? For now, we mostly have offset and limit. Tasks has 5
    • Should we have multiple code samples?
  • How do we make headings like “Filtering" and “Pagination” more visible in the API reference?
    • Possible solution: use sidebarDepth: 2
    • We will get too many headings in the sidebar. This can be distracting. We could use H4s instead of H3s, but this goes against using headers progressively
• Get settings endpoint
  • If we follow the new format, will we describe each field, or should we go with the table we have now?
    • If we go with adding the JSON response in the object heading, we will need to give some context for distinct, displayed, sortable and filterable attributes, stop words, and synonyms
  • Not all settings are objects; some of them are arrays of strings, e.g., displayed, sortable and filterable attributes, stop words, and synonyms
  • I think we should go with the current format for the settings routes. We should only use the new format if the object is composed of fields and objects, e.g., typo tolerance
    • The current format:
      • Explain the endpoint
      • Get
      • Update
      • Delete
• Search
  • I think this page should remain as it is; the only change I would like to make is to update the “Response” and “Example” headings to H4s so we don’t see them in the sidebar
• Update the router element colors. Patch and get have the same green
  • Put and post mostly use the same color
• How will this format work for endpoints that only have one field? E.g., version and health
• Will we explain the task object for dumps? Or should we link the tasks page?
• Put an * next to all mandatory parameters

[dichotommy]

Some notes I'd like to add to the agenda for our next meeting on this subject:

• Should object definition tables have a column stating whether or not the field is modifiable by the user?
• For endpoints that have both parameters and bodies, which table should come first?
• In the object definition section, shouldn't the code block displaying an example object come first? It seems like a useful piece of context
• H3 or H4 for examples? The PR uses both

[maryamsulemani97]

closing as all API related PRs have been merged