This seems to be written from the point of view that the "industry" is all enterprise SaaS software or something. I don't think I'd agree with calling any of these "industry best practices". Maybe "commercial business software best practices". #2, 3, and 4 aren't really applicable to a ton of software products. There's a lot of niche software that isn't intended for the general public.
API Practices If You Hate Your Customers
31–40 of 258 posts
Re: API Practices If You Hate Your Customers
#32I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough".
I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors.
When pointed out, the support answer was "we chose to give meaningful error messages instead of HTTP codes, that's why we respond with 200 in case there's an error in the request". Not the answer I was expecting.
Another annoying practice is to answer 2XX, put the request in a queue, and not provide ANY information about the queue, which can be minutes or even HOURS long. Debugging is a nightmare. The one I worked with who did that did not even have the excuse of being a startup or small company.
Re: API Practices If You Hate Your Customers
#33I really liked Strip's API version scheme and how well done it is. Recently I'm writing code that interacts with API of a Enterprise Product (fairly new, less then 3 years old) and its driving me crazy. They version every single API endpoints separately. So endpoint A to create a user is at version 7 but endpoint B to assign a group to a user is at version 4. WTF?
Stripe's API is well documented, but I don't understand why it uses form data instead of JSON. Seems weird/scary to have an API driven by completely unstructured text.
Re: API Practices If You Hate Your Customers
#34Earlier quoted context omitted.
> returning a null array to represent no items, and returning a single object without an array to represent one item. This just reminded me of a long ago incident at a former employer. I worked in back-office at a hedge fund and was responsible for maintaining several APIs & services written in C++. The APIs were pretty straight forward query for object(s), get back a vector of objects. If nothing was found, you'd ge…
I really don't like your story. The junior is clearly behaving immaturely and inappropriately by CCing others and not using an appropriate tone, but your response is to... retaliate by doing the exact same thing to him? What lesson is the junior supposed to learn here? That acting that way is A-OK as long as you have seniority and are factually correct? At least the junior has the "excuse" of being a junior, but real…
I'm not seeing anything wrong with what OP did. By CCing everyone, the junior is trying to make themselves look good by making OP look bad. The junior learned that if they act like an ass, especially an incorrect ass, the other employees won't tolerate it.
Re: API Practices If You Hate Your Customers
#35I was expecting to see two of my pet hates - returning a null array to represent no items, and returning a single object without an array to represent one item. I also once worked with an API where you had to send the data in POST format - abc=123&def=456. After much pressure from their customers, they finally relented and added an XML version of their API... where your request could look like this: abc=123&def=456 .…
For those Gophers reading this and sobbing silently, there may be hope: https://github.com/golang/go/issues/27589
Re: API Practices If You Hate Your Customers
#36I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough". I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors. When pointed out, the support answer was "we chose to give meaningful er…
> decided everything should return 200
Sounds like that decision came from someone who didn’t spend much of their career consuming APIs.
Re: API Practices If You Hate Your Customers
#37Earlier quoted context omitted.
> returning a null array to represent no items, and returning a single object without an array to represent one item. This just reminded me of a long ago incident at a former employer. I worked in back-office at a hedge fund and was responsible for maintaining several APIs & services written in C++. The APIs were pretty straight forward query for object(s), get back a vector of objects. If nothing was found, you'd ge…
I really don't like your story. The junior is clearly behaving immaturely and inappropriately by CCing others and not using an appropriate tone, but your response is to... retaliate by doing the exact same thing to him? What lesson is the junior supposed to learn here? That acting that way is A-OK as long as you have seniority and are factually correct? At least the junior has the "excuse" of being a junior, but real…
[deleted]
Re: API Practices If You Hate Your Customers
#38I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough". I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors. When pointed out, the support answer was "we chose to give meaningful er…
Ha, I love it when people make dumb excuses for awful decisions like that. /s
I much prefer colleagues who can say, woah that was dumb thanks for informing me of a better way. Making excuses doesn't help anyone unless one has a valid logical reason they did a certain thing, otherwise I DONT WANNA HEAR IT.
Re: API Practices If You Hate Your Customers
#39Earlier quoted context omitted.
> returning a null array to represent no items, and returning a single object without an array to represent one item. This just reminded me of a long ago incident at a former employer. I worked in back-office at a hedge fund and was responsible for maintaining several APIs & services written in C++. The APIs were pretty straight forward query for object(s), get back a vector of objects. If nothing was found, you'd ge…
I really don't like your story. The junior is clearly behaving immaturely and inappropriately by CCing others and not using an appropriate tone, but your response is to... retaliate by doing the exact same thing to him? What lesson is the junior supposed to learn here? That acting that way is A-OK as long as you have seniority and are factually correct? At least the junior has the "excuse" of being a junior, but real…
>Surely there must have been a better way for you to handle this situation.
The junior was in the wrong, so I think you'd agree that a correction is in order. Replying-all is one way to do such a correction. The alternative would be to force him to issue a retraction himself.
Re: API Practices If You Hate Your Customers
#40I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough". I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors. When pointed out, the support answer was "we chose to give meaningful er…
> decided everything should return 200 Sounds like that decision came from someone who didn’t spend much of their career consuming APIs.
But they are higher ups and should obviously be allowed to make ALL decisions, why listen to some developer who is beneath them. That dev has only spent the last 5 years working with APIs, databases, and web applications, what does he even know, probably nothing? /s