API design

[rachelheaven]

Agree API endpoints, query parameters and response objects. Capture in openapi with example data provided.

[metazool]

Will OpenAPI really benefit us much in this case? The OpenAPI specification says that the responses by no means have to be JSON types. But it seems like a lot of formalism to be defining response types for a couple of endpoints with few or no query parameters which return SVG or .dot responses. And it's our own internal API - not particularly intended for use beyond this small-scale innovation project.

I could understand the rationale for going through this for a public API which needs to be widely consumable, carefully managed and to persist, but don't think we need that overhead here.

[metazool]

There's also the FastAPI OpenAPI generation work linked in #10 https://fastapi.tiangolo.com/advanced/extending-openapi/ - e.g. the specification is derived from the code, not the other way round

[rachelheaven]

OK, not necessary to have too much overhead, but issue is here so that we agree what functionality is in the api and what is left to the visualisation client. API spec serves as useful documentation without having to read the code

[metazool]

I've only now realised how much OpenAPI functionality one gets from FastAPI for without having to customise anything. If you append /docs/ to the root of the service you'll see a generated SwaggerUI interface and openapi.json.