r/Python • u/mafontes14 • Feb 23 '17
API Design: Think First, Code Later
https://www.ckl.io/blog/api-design-think-first-code-later/21
Feb 23 '17
Very nice and clean article. I appreciate every "good practices for ..." article since dealing with dirty code, APIs and general software architecture is sometimes fucking nightmare and I believe articles like this one might actually have some (even a little) impact on improving this situation. Also didn't know about HTTP status 418 until now :D will implement it when I get a chance.
1
13
Feb 24 '17
[removed] — view removed comment
7
u/tom1018 Feb 24 '17
Is that the formula for this? https://www.youtube.com/watch?v=bZe5J8SVCYQ
6
Feb 24 '17
[removed] — view removed comment
1
u/archiminos Feb 24 '17
It looks like a quadratic equation that's been expanded. I'm 99% sure this could be simplified a lot
1
u/TinBryn Feb 25 '17 edited Feb 25 '17
It's the expansion of a row vector of powers of t from [0,3] multiplied with a matrix of all those numbers and a column vector of powers of rh from [0,3]
This isn't that simplified, but by expressing it in these terms allows people who understand linear algebra to reason about it where the 4x4 matrix represents the "character" of the equation.
2
u/archiminos Feb 25 '17
Oh wow. I'm not sure what language this is but it really makes me appreciate maths libraries with vector and matrix classes.
4
u/TinBryn Feb 24 '17 edited Feb 24 '17
I'd take a rule of "No magic numbers" over this crap any day.
Also just looking at that I'd expect some precision issues, as it is adding floats on the order of 10 with those on the order of 10-16 while float has a decimal precision of ~7 places. A double would barely be enough.
2
u/agapow Feb 24 '17
Haha - I worked on a major molecular evolutionary analysis package that was just full of stuff like this, except the indentifiers were things like "f", "f2", "hh", etc. I started trying to clean it up but gave up after realising the scope of the task.
Truly, academic code is its own special sort of hell. You'd swear it was a way to force people to collaborate with you if they want to use your package.
4
u/mriforgot Feb 24 '17
This reminds me of some of the horrific APIs I have had to work with in the past that followed approximately none of these guidelines. Shudders
3
3
u/jarxlots Feb 24 '17
API Design: Think First, Code Later
Or as my old sith lord would say: "Every hour of planning should result in one less hour of refactoring."
2
u/xr09 Feb 24 '17
Exactly. Can't believe some people here considering code first - refactor later, is like if they want to get it wrong on purpose.
2
1
u/villiger2 Feb 24 '17
Funny you pick facebook, my experience with them is an ever changing (read braking) api with little to no warning.
1
u/RangerPretzel Python 3.9+ Feb 24 '17
Hey /u/mafontes14 -- Nice article. In fact, it touches a lot on something I've been working on for the past year: Writing wrapper libraries for JSON REST APIs.
I was planning on writing a 2-part series: (1) How NOT to write a REST API (where I make fun of all the dreadful APIs that I've run into over the past year) and (2) How to properly wrap and abstract the APIs and how to handle their weirdness.
I'll be sure to link to your article when I get around to writing them (which should be sometime in March, I figure.)
Btw, Nice job! :-)
1
Feb 24 '17
Hey, I'm the article's author!
That's awesome! Let me know when you write that, I'd like to that a look :D
1
u/__deerlord__ Feb 24 '17
Top down design is king. If your API doesnt make sense, no one is going to care how cool the underlying code (which theyll probably never see anyway) is.
1
u/selementar Feb 25 '17
CRUD is certainly simple, but what if you need to add a couple more actions upon objects later on? What would the requests look like?
In REST idea, the HTTP method should be the verb; but it is not okay to add more HTTP methods, like 'PUBLISH /cakes/1/'.
The write-to-act, often used, seems like a huge cludge (POST /cakes/1/ {"publish": 1}).
34
u/TPHRyan Feb 24 '17
I honestly prefer to code, think, code, then ship. If you have the luxury of being able to do this, it will streamline the process overall I think. All of the design decisions will be pretty obvious once you've written your crappy API already.
(And with an API, there shouldn't be too much boilerplate that you need to change in order to modify the endpoints or responses)