Create API with machine-readable interface file (openAPI)

[simonsan]

Hey there,
I would like to propose that we create an API for the data at aoe2map.net so for example we can pull in some data and show it on an OBS-overlay or on the client.

I would further propose to use openAPI ("specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services"):
https://swagger.io/specification/

To easily create and validate the API file we can use apibldr
https://www.apibldr.com/

[HSZemi]

Why would you want to create the api file manually instead of generating it from the api urls? *scratches head*

Feel free to create a pull request that implements that feature!

[simonsan]

Why would you want to create the api file manually instead of generating it from the api urls? scratches head

Feel free to create a pull request that implements that feature!

Also good! :-)

[simonsan]

@HSZemi Is there documentation available regarding your API? I didn't find any docs here in this repository or on the website?

Nevermind! I just found out that you can generate some API yaml from Django and annotate it manually for your own use (so I'll do that instead thanks for helping out)
https://www.django-rest-framework.org/api-guide/schemas/

[simonsan]

That doesn't work with aoe2map sadly so it will need to be manually done. I started already and collecting the response formats for most of them to derive the schema.

Progress can be followed here, I will break down the examples, they come from the deriving process.
https://github.com/aoe-assoc/aoe2-rating-overlay/blob/devel-apis/api/aoe2map/aoe2map.json

@jerkeeler is using the "Django rest framework (DRF)" approach for aoestats.io. @goto-bus-stop was guessing that it could be not working because it "requires that the api routes derive from particular classes, but in aoe2map they're simple free functions". I'm waiting for some feedback of jerkeeler to see if the generation approach would justify not doing it manually for now and rather help refactoring to a class based approach using DRF. Thoughts?

EDIT: https://gist.githubusercontent.com/jerkeeler/ff6fcb540ebd175e0b5c13429004ae00/raw/9fcebce900e658614d2b342f424ea5f00814accf/aoestats-openapi.yaml

It would look mostly like this i assume so for now I feel it would make more sense to have it done by hand. And probably let it be updated in the future from exports of DRF. Leaving this open though.