Should updateXXX methods pass a single object or array of objects

[SidneyAllen]

We have 13 update endpoints which include passing a unique ID. They all currently require passing an object that contains an array populated by a single object. This functions properly across all 6 SDK languages. So, this isn't a bug per-se. The API accepts both a single object and an array containing a single object.

Assuming all 13 of the routes accept a single object, we could modify the OpenAPI spec on these 13 "update" methods to accept a single object instead of an object with array containing a single object.

This would be a breaking change for any developers currently using these methods in our 6 SDKs (major versioning required), updates to unit tests and 6 companion apps that demonstrate how to use them. Also, updates to meta data used to generate our SDK documentation with runnable code examples.

If I recall, the reasoning behind using the array vs, the single object is that Xero's API returns an array of objects even when performing a GET with a unique ID.

For developers who've just retrieved an Invoice, they could modify that object already inside the array and pass it to an update method without having to create a new Invoice object and populate it. Perhaps this is not common and should be discounted as a reason.

We are interested in hearing from developers about how important this request is and if there is anything specific about your use case or programming language that makes this more acute.

Thanks for your input

[adamreisnz]

As a developer and long-time consumer of the Xero API, and as I've commented in the linked post above, I definitely think accepting a single object instead of an array with a single object inside will be more user friendly for developers. I would even go as far as just passing in the ID only, instead of an object with an ID, because that is the only thing the API really needs at that point.

The Stripe API is a good example of how this is done really well, and you simply pass in , and you're done. No need to think about convoluted array structures, making sure your objects keys are correct (was it invoiceId, invoiceID, InvoiceID, invoice_id, or ....?), or having to look up other implementation details.

Less is more, and allowing us to pass in less information into the API to get the same outcome will improve the legibility and usability of the API drastically.

[AGenius]

Personally I agree with @adamreisnz

Less is more.

This is one of the reason I have created my own API to front end the Net-Standard API . I have simplified methods to get an invoice and I retrieve LISTs of objects and not an object with a list.

So in short I am normalize the API in the way I like to use it.