search

ModaOperandi / agora

Engineering standards
3 stars 1 forks source link

JsonAPI specification #34

Closed vdumitrescu closed 4 years ago

vdumitrescu commented 4 years ago

When I started working on preferences-api, I was told that the data we consume and produce must follow the JsonAPI specification, because this is how mojo works.

However, when I wrote the client for preferences-api inside mojo, I noticed that there too we have no support for the specification, but rather a direct approach of wrapping the vanilla Json in a minimal JsonAPI structure (example).

Since we're not using the specification properly, why are we using this at all?

The alternative is an API-first approach, where the only way to describe an API and its data is through an IDL, and all necessary code is generated from that IDL, and nothing is written by hand. This eliminates any confusion about field names, their types, the order, and so on. Whether we adopt something like OpenAPI (formerly known as Swagger) or something similar, there should be no need for JsonAPI.

upperbounds commented 4 years ago

@figgybit @norbert-vamos Any thoughts from a historical perspective?

rlmartin commented 4 years ago

FYI I spoke with @figgybit and he confirmed that there is no reason (other than legacy clients) to stay with JsonAPI. Probably would make sense to migrate Mojo APIs off of JsonAPI at the time that we're flipping to a new microservice. i.e. new microservice does not use JsonAPI, has a new major version. Old API at old major version is still available in Mojo. Cut over clients based on versioning (since both sets of infra will be running) and tear down the old version once it stops receiving traffic. Migrating off of JsonAPI entirely within Mojo would take a similar approach with multiple versioned endpoints and probably isn't worth the cycles.