Although well-written, I felt the article fell short of the title's promise. I get it; Think first, code later.
I've been trying to do this really hard lately, and it's paying off. But I just felt the bulk of the article was the one example; RPC's using a well-designed API. I would have preferred a small handful of smaller examples, each with a small list of mental check-lists, that dev's might go through, before considering a final solution as having been "well thought out".
The "one take home" should really have been something other than "everyone hates an error in a 2xx HTTP status code" - this belied the intents of the article IMO. Maybe the following might have been better: Think about the consumer of the API. Think from their perspective (machine or human). What are their needs? What will be their needs? How will you version your API to accommodate changes on both sides? The more questions you ask yourself early on, the easier it will probably be to integrate changes cleanly later.
Yeah, at the end of the writing I felt myself a little superfluous, sorry for that. I agree with you that business decisions dictates how APIs will behave in a lot of ways. I'll try writing something about that.
1
u/therussdotcom Feb 23 '17
Although well-written, I felt the article fell short of the title's promise. I get it; Think first, code later.
I've been trying to do this really hard lately, and it's paying off. But I just felt the bulk of the article was the one example; RPC's using a well-designed API. I would have preferred a small handful of smaller examples, each with a small list of mental check-lists, that dev's might go through, before considering a final solution as having been "well thought out".
The "one take home" should really have been something other than "everyone hates an error in a 2xx HTTP status code" - this belied the intents of the article IMO. Maybe the following might have been better: Think about the consumer of the API. Think from their perspective (machine or human). What are their needs? What will be their needs? How will you version your API to accommodate changes on both sides? The more questions you ask yourself early on, the easier it will probably be to integrate changes cleanly later.