We ship a document-review API from a Go service at Landvex. As we speak the report is six named dimensions, every verified / deviation / unclear. There isn’t a total rating, and I wish to hold it that method.
What I’m undecided about: we might have a seventh query later, or we might have to separate one of many six as soon as we perceive a doc household higher.
– Do you deal with the scale as an extensible record within the JSON (purchasers should ignore unknown names), or as a closed struct that forces a v2?
– How do you cease an previous consumer from inventing a abstract rating the second it sees an inventory as a substitute of six mounted fields?
– Any Go API design you regretted right here — protobuf enums that couldn’t develop, or a map that grew to become a junk drawer?
I’d somewhat model actually than paint ourselves right into a nook.
I might hold the scale as an extensible record, not a closed struct. Return a slice of objects, every with a secure key, a standing, and any element, and doc that purchasers should ignore unknown keys. That method including a seventh dimension is an additive change, and splitting one means including new keys and deprecating the previous one, by no means reusing its identify.
Don’t return an total rating in any respect, and say so within the API docs. If there isn’t any rating discipline, an previous consumer has nothing to sum, and a consumer that wishes a abstract can compute it domestically. A listing doesn’t by itself invite a rating, a rating discipline does.
In Go I might use a slice of structs with a string key kind, not a map and never a protobuf enum for the scale. A map loses ordering, and an enum is difficult to develop with out breaking older generated code. Add a schema_version discipline to the report so a consumer can inform which set of keys it’s seeing, and hold the semantics of the prevailing keys unchanged in v1.
My expertise: API Versioning is a ache which I attempt to keep away from generally.
However selecting a foul API structure due to worry for future adjustments is worse.
Design your JSON for optimum use and consumption. Introduce further attributes with out growing the API model, as a result of extension is a backwards appropriate API change. However when you actually have to separate a query take the step and make a V2 API, since this can be a change which isn’t backwards appropriate.
I’d hold the scale as an open record of named outcomes and model the report, not every query. Purchasers that ignore unknown names will survive a seventh dimension. The change that truly hurts is splitting one of many six, as a result of previous purchasers nonetheless search for the previous identify. That’s when a path model is cheaper than being intelligent.
