How to Design Better APIs
I’m gonna say it:<p>Many rest apis are lazy and developer friendly, not consumer friendly.<p>If you have related resources,  let’s say, product and product options as two distinct endpoints:<p>- &#x2F;api&#x2F;product<p>- &#x2F;api&#x2F;options<p>Then, and I want to be clear here, it is <i>impossible</i> for a client to perform an atomic operation on multiple distinct objects types.<p>Let’s say the client needs to add a product with a single option or fail.<p>You can create a product.<p>You can create an option.<p>You can add an option to a product.<p>…but, at some point in time, a product will exist with no options on it.<p>This kind of “pure” rest api is simply convenient to the <i>developer</i> because they push the problem of object consistency to the client.<p>…but that’s not a client concern.<p>If a product needs to be associated with an option on creation, then your api should offer that as an endpoint.<p>It doesn’t meet the “standard” for a rest api?<p>Too bad.<p>Write APIs that do what the customer &#x2F; consumer needs <i>not</i> lazy APIs that just make your life easier.<p>I’ve worked with a lot of APIs and you know what I do not give the tiniest moment of care about?<p>Consistency.<p>I do. Not. Care. If POST &#x2F;api&#x2F;foo creates an object, or if the endpoint is &#x2F;api&#x2F;foo&#x2F;create.<p>Messy? Inconsistent?<p>I don’t care. Just put it in the documentation and I’ll find it and use it.<p>…but if your api forces object relational consistency onto me as an api consumer, you have no <i>idea</i> how much pain and hassle you’ve caused me having to implement my own set of fake transactions over your stupid api.<p>Please, write APIs for consumers, not according to “the rules” of rest APIs.<p>…and provide documentation. :)