API reference reformatting

[maryamsulemani97]

Based on this discussion, we want to standardize and reformat the API references.

Possible template

1. A brief introduction + description
2. Link to guide
3. List endpoints: (possible order)
   • List all
   • List one
   • Create
   • Update
   • Delete all
   • Delete one
4. For each endpoint (the following do not apply to all endpoints):
   1. What it does
   2. <RouteHighlighter> element
      1. Its convention to put path variables in {} in endpoints. But I see a lot of documentation without it as well
   3. Path variables
      1. Use a table with the name, type, description columns
   4. Query parameters
      1. Use a table with the name, type, description, default value (optional) columns
   5. Fields returned
      1. Use a table with the name, type, description columns
      2. What would nested objects look like?
   6. Request body
      1. Use a table with the name, type, description columns
      2. JSON sample
   7. Example
      1. Code sample
      2. Response
         1. Add a short description if needed
         2. Can we do this for each response? I think this will be a lot more helpful compared to the current errors page that we have. We can’t cover everything but maybe the major ones?
         3. Possible problems: May get too long

Questions:

1. Should path variables be in bold or back ticks? index_uid or index_uid?
2. Are there any parameters that have a max/min value?

[maryamsulemani97]

Hello,

I have created a PR for this. It's not a template, it's more of a visual reference for what we want our template to include. I also think we need colors. I love Spotify's API reference, it doesn’t have too many colors. I like what I have for the pages called: POST, PUT, PATCH, and DELETE. If anyone has any suggestions, please lmk! The pages called: GET visual reference 1 and GET visual reference 2 have different formats.

GET visual reference 1

There's 2 headings with the same format, I used two to see what the page would look like for an object with fewer fields vs. more fields. I used a table for explaining the fields returned.

Pros

Its a table. Tables look super organized, the user will be able to view all the information without having to scroll too much.

Cons

The table is ugly. I don’t like how the code snippets overlap.

GET visual reference 2

This format starts of with the object like Stripe and does not use a table for explaining the fields returned. This means not all H2s will be an endpoint. I used two to see what the page would look like for an object with fewer fields vs. more fields.

I like MailChimp's API reference, they don’t use tables.

Pros

No tables!

Cons

• Goes against our convention of H2=endpoints. I personally don’t think it's that big of a problem if we're consistent with it and it works. Currently we have two examples where we're explaining the returned fields:
  • Stats and keys (part of v025): I don’t like it because we explain some fields in one endpoint and some in the other. This means the user will have to scroll between them to get the complete information
  • Tasks (part of v025): The tasks object is explained on a different page
• The fields part can get long so the user may have to scroll between the fields We could also use what we have in GET visual reference 1 without tables and GET visual reference 2 with tables.

[maryamsulemani97]

We will start with:

• https://github.com/meilisearch/documentation/issues/1526
• https://github.com/meilisearch/documentation/issues/1527
• https://github.com/meilisearch/documentation/issues/1528

[maryamsulemani97]

Update pages to add sidebarDepth: 2, make all Example, Query parameter, body subsections, etc. headings H4 so any other things that aren't endpoints (e.g., object definitions, special subsections like filtering or pagination above) are more visible

[maryamsulemani97]

fixed in the API reference PRs