Open API spec does not appear to be correct on the website

wasadigi commented 2 years ago

Hi there,

This is not really an issue about egoscale, but I didn't know in which repo to file the issue. I was able to confirm the issue by looking at eh code of the exoscale CLI, which uses the API.

Here is what I have observed:

I am using the Exoscale REST API v2, as documented here: https://openapi-v2.exoscale.com/
I am able to make successful calls, by following the signature process
When I call /instance, I get a list of compute instances but the JSON payload does not follow the API spec; for instance, in the instance-type attribute, I only get the id value and not all the details of the instance type. I have seen that the CLI is actually making calls to 2 endpoints and caching the details of the different instance types.

If I am correct, is there an easy way for you to fix the Open API spec? Or do you have a pointer to another version?

By the way, couple of unrelated questions (please let me know if there is a better forum to ask these types of questions):

is it true that there is no pagination on the endpoints? (or is that a not documented feature?)
is it correct that there is not way to specify filters when calling the endpoints? For instance, if I want to get the sub-list of instances that have a certain attribute (I am thinking about labels), can I do that? Or do I have to parse on the client side?

Thanks!

pyr commented 2 years ago

Hi @wasadigi,

Thanks for digging into this, and for exploring the API

OpenAPI spec conformance

Since OpenAPI does not mandate field presence and to avoid large repetitions of resource definitions, the Exoscale API uses shared resource definitions. Field presence is dependent on context. As a general rule, listing type calls (e.g: list-instances) expose few properties while resource details type calls (e.g: get-instance) expose more details.

If you want to explore the calls made by the Exoscale CLI, you can use the EXOSCALE_TRACE environment variable, for instance: env EXOSCALE_TRACE=1 exo compute instance list

Paging

At the moment, no paging occurs (the nascent list-events call will likely introduce paging), all instances are retrieved for list-instances.

Filters

Filters are planned but not provided as of yet, for now client side filtering is mandatory. When implemented, they will be exposed as query parameters.

I hope this helps!

wasadigi commented 2 years ago

Thank you for the clarification @pyr!

exoscale / egoscale