API Documentation vs API


in general I like the idea of squidex and how it works.
What was a bit disorienting for me, is how to get to the API full documentation:

When starting a new project, you get a new dashboard which has a “API-Documentation” button:

Clicking this button leads you to the full documentation:

To the left inside the project there’s also a menu item “API” which contains two sub menu items “GraphQL” and “Swagger”.

Clicking “Swagger” only shows “Authentication” instead of the full API Documetation and downloading the “Open API specification” also only contains the “Authentication” part.

Maybe I’m missing some conceptual information here but my expectation would be to get the “Open API specficcation” for the complete API.



Hi, you are right. There is a lot of room for improvements.

Basically there are 3 APIs:

  1. The static REST API to manage schemas, users, settings, assets and so on and which is the same for all users. The API documentation is created from the static type information of the controllers. This is what you see at when you click the API button in the dashboard.

  2. The “dynamic” REST API that is generated on the fly from your published schemas and which obviously is different for every app. The reason you only see the authentication part is that you have probably no published schemas yet.

  3. The “dynamic” GraphQL API (queries only) that just uses a different approach for generating the documentation.

There are 2 reasons why I keep the two APIs (1 + 2) separate:

  1. To avoid naming conflicts.
  2. It is just much easier code-wise, but this can probably be solved.

But you are totally right, we need a better way to communicate the differences, e.g. by using different names.

This is how my dynamic REST API looks in one my apps:

Thanks for the explanation.
If I understand things correct, the first API is the “admin” API while the second one is the sort of “content” API.

Kind of, the assets are an exception of that, because you would probably also call it “content”.