reconciliation-api / specs

Specifications of the reconciliation API
https://reconciliation-api.github.io/specs/draft/
30 stars 9 forks source link

Change the format of reconciliation queries, responses and data extension responses #92

Closed wetneb closed 1 year ago

wetneb commented 2 years ago

Closes #33. Part of #84.

This removes the use of arbitrary keys in JSON objects. As a result we are no longer using "patternProperties" in our own JSON schemas. This is obviously a big breaking change, which I intend to bundle with other breaking changes related to #84 (such as #91).

I made some choices in the process, and they are debatable:

osma commented 1 year ago

This looks like a good step in roughly the right direction. What I dislike is the use of top level arrays in JSON, instead of objects. The main argument against this is the lack of extensibility - you cannot easily add more fields later (see e.g. this blog post and this SO discussion).

For the queries, instead of [ query1, query2, query3... ], I suggest this:

{
  "queries": [ query1, query2, query3... ]
}

and similarly for the responses:

{
  "responses": [ response1, response2, response3... ]
}

This would allow adding new fields later (e.g. related to count of results or paging) if that becomes necessary.

wetneb commented 1 year ago

That makes a lot of sense! I have just fixed that following your suggestion. Let me know if you can think of anything else.