API Practices If You Hate Your Customers • Hacker News Board

Re: API Practices If You Hate Your Customers

#221

Post by jefftk » Thu, Dec 12, 2019, 1:40 PM UTC

tasogare wrote: post #196

arethuza wrote: post #168

Earlier quoted context omitted.

Unfortunately I have vivid memories of one API I worked with (many years ago) that included entire encoded XML documents as attribute values within top level XML. At least there was only one level of recursion. Still, perhaps not as bad as using XML documents as database keys...

I saw that in HTML. Not from a professional developer but it still blow my mind. That was the final straw that made me quit the project.

I've needed to do that for HTML. If you need to put part of a document inside an iFrame (perhaps because you don't trust it) you have your backend generate and nest it.

Re: API Practices If You Hate Your Customers

#222

Post by zeveb » Thu, Dec 12, 2019, 2:22 PM UTC

yardstick wrote: post #212

lazyasciiart wrote: post #179

Earlier quoted context omitted.

You don't have to. Plenty of times, a 404 is all I need to know. Why make the client check two different locations?

If the 404 is due to the client calling the wrong URL, rather than trying to access an entity/record that doesn’t exist, the client code will incorrectly assume the entity/record doesn’t exist when it actually does. Eg an API has a /discountvoucher/ID, so your client can enter a discount voucher code and get info on the voucher. If your client code calls /voucher/ID instead, under the 404 approach you would incorrect…

> If the 404 is due to the client calling the wrong URL, rather than trying to access an entity/record that doesn’t exist, the client code will incorrectly assume the entity/record doesn’t exist when it actually does.

There's the root of your error: the entity is the URL; the URL is the entity. If the client requests a URL which does not exist … that URL does not exist.

If the client requested a URL which does not fit the expected schema … that URL does not exist.

Once you embrace RESTfulness & HATEOAS, life gets so much simpler. Also, every time you return errors in a 200, God kills a kitten. If for nothing else, think of the kittens!

Re: API Practices If You Hate Your Customers

#223

Post by benoitg » Thu, Dec 12, 2019, 3:18 PM UTC

Ididntdothis wrote: post #62

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.

You can force PHP to handle sngle-element arrays consistently, with the SOAP_SINGLE_ELEMENT_ARRAYS option, the behaviour is much saner when enabled.

Re: API Practices If You Hate Your Customers

#224

Post by jayd16 » Thu, Dec 12, 2019, 3:18 PM UTC

mleonhard wrote: post #211

jayd16 wrote: post #164

Earlier quoted context omitted.

>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. So here's the deal with this pattern...If you're returning a typed error response, something the client application should interpret, you want to be able to know which error responses will actually ha…

The client should try to parse the response body only if it has the appropriate Content-Type header value. It should not assume that responses with various status codes have a particular body format.

Do you suggest having a content-type header specific to your app? Something like "application/my-app+json"? Will most tooling handle this correctly? In my experience the always 200 api style is a lot more common.

Re: API Practices If You Hate Your Customers

#225

Post by Ididntdothis » Thu, Dec 12, 2019, 3:22 PM UTC

benoitg wrote: post #223

Ididntdothis wrote: post #62

Earlier quoted context omitted.

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

You can force PHP to handle sngle-element arrays consistently, with the SOAP_SINGLE_ELEMENT_ARRAYS option, the behaviour is much saner when enabled.

Good to know! Unfortunately I have a call to a “FixSoapArray” all over the code already :(

Re: API Practices If You Hate Your Customers

#226

Post by jandrese » Thu, Dec 12, 2019, 3:31 PM UTC

chihuahua wrote: post #9

jandrese wrote: post #7

Earlier quoted context omitted.

What would you suggest instead of an empty array for a 0 item return?

The person you replied to doesn't like returning "null". He/she would probably prefer returning an array that contains 0 items.

He called it a "null array" which I interpret as an array containing zero items. If it was just a plain old null then yeah, that's super annoying.

Re: API Practices If You Hate Your Customers

#227

Post by diehunde » Thu, Dec 12, 2019, 3:40 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…

I think that 200 status code for everything is such a bad practice. I'm surprise the amount of people here that are OK with that.

Re: API Practices If You Hate Your Customers

#228

Post by jayd16 » Thu, Dec 12, 2019, 3:57 PM UTC

sho wrote: post #180

jayd16 wrote: post #162

Earlier quoted context omitted.

This is not true. Counterpoint, responses like 404 or 503 Bad Gateway do not come from the destination server. They do not indicate the intended server received your request.

404 and 500 should come from the destination server. You are correct that 503 would not.

Hmm are these assumptions valid? Can't a misconfigured load balancer cause a 404? Couldn't a bug in nginx, node or an app server produce a 500 response outside of your control?

Re: API Practices If You Hate Your Customers

#229

Post by tsukikage » Thu, Dec 12, 2019, 4:20 PM UTC

A seemingly common one in the move fast and break things world is to provide all information in the form of hello world tutorials and youtube videos. The source code is its own reference, amirite?

Re: API Practices If You Hate Your Customers

#230

Post by pavel_lishin » Thu, Dec 12, 2019, 4:29 PM UTC

akvadrako wrote: post #156

wool_gather wrote: post #75

Earlier quoted context omitted.

No, the "completely invalid query" is 400. 404 is only for "the request makes sense but that specific resource doesn't exist".

In this case it’s a 404 because the query URL pattern doesn’t exist - the most common cause of 404s.

Same thing, no? If I ask for /api/user/238885 and I get a 404 back, it's because the resource "user" with ID of 238885 doesn't exist. If I ask for /api/banana/wharrgarbl, it's because the resource "banana" with the ID of "wharrgarbl" doesn't exist.