API Practices If You Hate Your Customers • Hacker News Board

Re: API Practices If You Hate Your Customers

#61

Post by shantly » Wed, Dec 11, 2019, 11:11 PM UTC

saagarjha wrote: post #41

gruez wrote: post #39

Earlier quoted context omitted.

>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.

There's no need to shame people who are wrong.

If they're trying to shame or chastise others, while being wrong, seems fair to me. Then again, I subscribe to the "play stupid games, win stupid prizes" school of dickish behavior correction.

Or, to defer to the ever-wise Gods of the Copybook Headings:

"What's good for the goose is good for the gander".

Re: API Practices If You Hate Your Customers

#62

Post by Ididntdothis » Wed, Dec 11, 2019, 11:15 PM UTC

gtsteve wrote: post #2

I 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 .…

“returning a single object without an array to represent one item.”

I saw the same thing when working with PHP consuming data from a SOAP endpoint. First I thought PHP is stupid. But then I realized that XML can’t model single item arrays versus single objects. They look the same. JSON is better that way. You can model empty arrays and single item arrays.

Re: API Practices If You Hate Your Customers

#63

Post by gamblor956 » Wed, Dec 11, 2019, 11:15 PM UTC

saagarjha wrote: post #41

gruez wrote: post #39

Earlier quoted context omitted.

>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.

There's no need to shame people who are wrong.

Normally that would be true.

But it's necessary to shame people who work the trade desks, or else they will never learn.

Re: API Practices If You Hate Your Customers

#64

Post by jiggawatts » Wed, Dec 11, 2019, 11:16 PM UTC

gtsteve wrote: post #2

I 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 .…

I had this happen with a vendor that was told that they needed to add REST support to their legacy Java app. They turned up with an API that encoded XML as base64 and put that in a POST variable on HTML page. Then they added their own crypto on top with hard-coded RSA keys. They helpfully included both the public and private keys in their documentation.

When they turned up for a meeting to present the fruits of their labour they got patted on the back by all the managers for a job well done. Record time too!

They faces fell when I told them that I'm flat out rejecting their API design and that they will have to start from the beginning.

Their excuse for the design was that ampersands are too hard to process, so base64 encoding made them "safe" to include in the REST API.

Sometimes you just have to put your foot down about this kind of idiocy.

Re: API Practices If You Hate Your Customers

#65

Post by shantly » Wed, Dec 11, 2019, 11:16 PM UTC

inputespresso wrote: post #33

NedIsakoff wrote: post #6

I 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.

What's unstructured about HTML form data format?

Re: API Practices If You Hate Your Customers

#66

Post by jan6 » Wed, Dec 11, 2019, 11:17 PM UTC

tomaszs wrote: post #26

Personally i think API should be obligatory. Every company should provide it with respect for private data. Additionaly if a company does not have it, it should be prohibited to block automatic measures to process the system and data. There should be a pricing model to cover basic expenses made by the API usage. Maybe you wonder why on earth it should be legally allowed to process automatically system data? We have a…

of course, I think everyone here would agree it's always good to have an API... too bad you're not gonna succeed in pushing this "rule" out, especially scraping stuff...bot bans are in part because it's rather easy to overload the system with bot calls, which, since they use same page as users, will also affect normal users...especially taxing if the page is dynamic with server-side stuff, like maybe some aspx or php page, which at best would just hog the system resources, at worst could possibly break altogether (most likely due to no free ram), etc... I'm no expert tho, so these specifics might be wrong...

Re: API Practices If You Hate Your Customers

#67

Post by corebit » Wed, Dec 11, 2019, 11:21 PM UTC

aldoushuxley001 wrote: post #59

hpoe wrote: post #20

Earlier quoted context omitted.

I would argue the primary benefit of having an API even if not made public is that it will encourage better architecture , design, and development making the product more maintainable over the long run. It also means you can scale if you ever do need to add a customer that wants to make use of an API. Saying not to do an API because customers don't want it is similar to not using source control because you're the onl…

Is having an unnecessary API really better architecture though? It adds quite a bit of complexity and there are other ways to address separation of concerns.

Depends on how big your team is. If it's just you and you feel like you dont need one then dont. If its 3 teams of 10 then an API is extremely helpful. It's a great way to frame conversations in something beyond personal preference.

Re: API Practices If You Hate Your Customers

#68

Post by paulddraper » Wed, Dec 11, 2019, 11:22 PM UTC

e9 wrote: post #52

Fradow wrote: post #32

I 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…

It depends. I've seen bigco use this technique and their reason was that they wanted to separate problems with API and request from actual issue with their servers/platform. So if you get 200 it means they received request successfully but if there is issue with request they'll include error in response with 200. If it's anything else then there is a networking or delivery problem. It's not standard way to handle thi…

For example, suppose you want to distinguish between a missing/deleted resource /myuser/23123 and a completely invalid query /muser/23123.

Both of these are 404 (or 410 for permanent caching) responses according to HTTP, though they have very different reasons for "non-existance".

Re: API Practices If You Hate Your Customers

#69

Post by [deleted] » Wed, Dec 11, 2019, 11:23 PM UTC

Fradow wrote: post #32

I 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…

[deleted]

Re: API Practices If You Hate Your Customers

#70

Post by davalapar » Wed, Dec 11, 2019, 11:26 PM UTC

e9 wrote: post #52

Fradow wrote: post #32

I 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…

It depends. I've seen bigco use this technique and their reason was that they wanted to separate problems with API and request from actual issue with their servers/platform. So if you get 200 it means they received request successfully but if there is issue with request they'll include error in response with 200. If it's anything else then there is a networking or delivery problem. It's not standard way to handle thi…

If the server got an issue with your request it can return 400 (Bad Request), which means that the server has received it successfully before acknowledging it as a bad one.

Even then, if the server returns 400 (Bad Request) the server can still attach a response body to that, in plain text/plain, application/octet-stream or even application/json, which could contain elaborate information.