There should be a working and fully functional API documentation for the MVD

[AlWitton]

Feature Request

Improve documentation

Which Areas Would Be Affected?

• SwaggerUI accessable through git, which is currently not working
• MVD

Why Is the Feature Desired?

Well... as for now I only got some API calls from the samples folder within the DataspaceConnector git. Currently I want to access the available catalogs in my dataspace through a simple post or get request. It is ok that the API is split into default, data and ids for each connector, but only stating this in the logs of the compose file, which prints messages from the crawlers is just bad and not really developer friendly. The API provided in the git is unusable as it always throws 404 errors, so I would like to have a better documentation in the README files delivered with this project.
I was able to figure out some calls, but some are still a big question mark for me because there is no documentation, no example, nothing to use at all to get a hint how to get desired features working within this testbed.
Furthermore it would be nice to have known in advance that for some of the APIs there are restrictions but others are not affected by it. For example: I can't access the 8181 port service through IP but only through localhost. Seems like within the certificate there is an explicit DNS name set to localhost or company1/2/3.
To get the desired calls for my task (to find out what is offered within my dataspace I scoped through the entire sourcecode of the dashboard to see what kind of calls are used there. I got a few ideas but nothing that pushed my usecase forward.

How does anyone can contribute to the system if the information are scattered or not at all visible in the first place?

Solution Proposal

Just document how to interact with the dataspace from a connector.
An example for each possible call and for each possible api service
I want to know what do I need to call, where - port and api path(default, data, ids) and with what kind of payload without having to go through every single file.... I want it to be present on a centralized documentation as entrypoint, from where I can navigate through everything.

Type of Issue

Improvement

Checklist

• assigned appropriate label?
• Do NOT select a milestone or an assignee!

[paullatzelsperger]

I'm assuming you are using the docker-compose variant to test out MVD, in which case the there are no certificates and name resolution (localhost vs company[1|2|3]) is handled by docker. Furthermore, looking at the docker-compose file and the Dockerfile it should be fairly easy to see what ports and paths are exposed and how they are mapped.

MVD itself does not define an API, it merely pulls in several components, some of which expose an API, and combines them. Some of them bring their own API, and MVD merely configures (exposes) it. Most of our APIs are documented in SwaggerHub.

On a related note, we employ the concept of configurable webserver contexts, which is explained in detail here.

I suggest reading up on documentation on the Connector (as it is the core component) and checking out some samples.

If I understood correctly in your particular use case you want to look at a dataspace's "catalog" (i.e. who offers what), which is handled by the FederatedCatalog. Unfortunately it's query API is not yet getting published to SwaggerHub, but it should be easy enough to generate a swagger-ui out of it or generate a client in your language of choice.

edit: opened eclipse-edc/FederatedCatalog#34 for publishing the Catalog's API to swagger hub