What is the reason for the custom entrypoints?

[micheh]

In API Platform there are two routes:

1. api_entrypoint with the default route /api.{_format}
2. api_doc with the default route /api/docs.{_format}

I don't quite understand why the custom api entrypoint exists and why the information is a little different for each format:

• HTML: Same page as the documentation.
• JSON-LD: Lists the names and url of each resource as an object (for example book: "/admin/books").
• JSON Open API: Lists the fully qualified PHP class names of each resource as an array (for example App\Entity\Book).

I would have expected that the entrypoint is simply the base url like http://example.com/api where you can find the HTML documentation (or at least a landing page that leads to the documentation).

In the Hydra specification the entrypoint is mentioned in the Hydra API documentation file and is simply the base url:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@id": "http://api.example.com/doc/",
  "title": "The example.com API",
  "entrypoint": "http://api.example.com/",
  ...
}

Source: https://www.hydra-cg.com/spec/latest/core/#example-17-retrieving-a-hydra-api-documentation-to-obtain-the-main-entry-point

I'm wondering why this is implemented this way by default, because the setup with the custom entrypoints may be a bit confusing. In the default config, users will probably go to /api to find the Swagger UI documentation. At the bottom, there are the links to the other formats like JSON-LD and JSON Open API. However, those links use the current route (api_entrypoint if you visit /api). This means that the user will see those custom entrypoints in JSON-LD or JSON Open API formats and not the standard documentation file like you may expect. And in the HTML format, you have two pages with the same content.

Maybe it is worth considering to remove those custom entrypoints in different formats and only have one HTML entrypoint if those entrypoints have no special meaning? The single entrypoint can then show the HTML documentation or redirect to api_doc by default.

Alternatively, it would probably be a good idea to add the link to the documentation to the entrypoint in all formats, as this is probably the information users are looking for.