https://wiki.softwareheritage.org/index.php?title=Glossary for the terminology

To improve on this, I propose the following:

• /api/ is the documentation page (pretty much like github's developer page). This will explain what is the api, its terminology, some examples on how to use it in general (as the main description is described).
• We add a table of contents (TOC) to easily browse it
• The api endpoints listing is removed from that page. pros: - the page is less long to load
  • not quite maintainable when we'll have other versions cons: an indirection (well, not really so since the other page /api/1/ is directly accessible)

• Add a link to the api endpoints listing for the version 1 (that would be /api/1/ described below).

• /api/1/is created and this lists the opened and upcoming api endpoints. This is what was used to /api/ but improved with:
  • a link back to the general documentation /api/
  • a small general description and legend about what an upcoming api endpoint is
  • a TOC for accessing the endpoints and their small description

I'll deploy a production version with this approach.
We can either revert it it's not satisfactory or improve on it.

I think this goes in the right direction, towards T620.

Deployed:

• Main documentation: https://archive.softwareheritage.org/api/
• List api endpoints v1: https://archive.softwareheritage.org/api/1/

In T630#10990, @ardumont wrote:

Deployed:

Thanks, this is generally really nice!
And yes, I confirm the use case you imagined and that taking inspiration from GitHub doc would be nice, as that doc is both a good reference and very concise.

• Main documentation: https://archive.softwareheritage.org/api/
• List api endpoints v1: https://archive.softwareheritage.org/api/1/

However, I've a minor problem with the implementation. The curl examples are hardcoded in the introductory doc, and at this stage it is still entirely possible we will make changes like add/remove dictionary entries; having to maintain those example snippets by hand will be a pain. After all, one of the points of the examples link also in the docstring was to not have to do that. Also, those examples should ideally be the same that the user will find when visiting the documentation for specific endpoints.

I see various possible solutions for this:

1. either we have a way to statically generate those example snippets (e.g., some script that we execute from the source code of the webapp, which will update the doc automatically and then we commit it and push)
2. the examples in the API overview are dynamic, and will invoke the real examples URL before returning the page
3. we remove the examples from the overview page; users will have to visit the individual endpoint doc pages to have real examples

(2.) is highly suboptimal in terms of performance, caching, etc.
(1.) would be ideal, but might be overkill to implement right now.
(3.) is the easy way out, even if it gives us a less complete overview page.

I generally agree with your comments.

1. would be ideal indeed. If we'd want that I'd rather have the time to investigate properly. We don't have that much time left in regards to other new webapp tasks.
2. API overview is currently static. We would then need to rework the current implementation. Plus, if you add the rate limiting dimension, this won't do well.
3. I don't like the idea of removing examples. Examples are a great way to test our understanding.

I see a 4th option though which is a middle ground between the possibilities you mentioned.
If the users wants to see the results, they decide to do so by following the link that we could provide as example.
We give the users the choice to assert and check the result.

To avoid having rate limit issue because of those example, we should use api endpoints which are not too sensitive (if such endpoints exist).
The examples I used are mostly concentrated on the stat/counters example which could be cached.
And the other example I used, which is against /content, can be targeted on a less important endpoint.