Consider using existing standards to define API structure and behaviour

[ben-ryder]

Describe your improvement
Consider using existing standards to define API structure and behaviour

Is your suggestion related to any problems?
The API is mostly custom right now, and while I think it is easy to use adopting widly used standards and tooling would make the API more approchable and possibly allow for easiler integration with developer tooling and the ecosystem as a whole.

Additional context
Consider things such as the JSON:API spec, OpenAPI spec etc.