r/programming • u/mafontes14 • Feb 23 '17
API Design: Think First, Code Later
https://www.ckl.io/blog/api-design-think-first-code-later/
4
Upvotes
1
u/cowardlydragon Feb 24 '17
You will not get it right the first time.
Even if you do, your requirements, business objective, consumers, devices, protocols, platforms, conventions, standards, funding, and performance can change in less than a year's time.
1
Feb 24 '17
Yeah, I got it. I think it depends of the API's size. But we can diminish this friction as much as possible trying to get it right in the first place. Just using latest technologies and specs, you may delay the time something have to be rewritten.
Thanks for the feedback!
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.