Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

API Practices If You Hate Your Customers

queue.acm.org

Post reply on HN
Print view View original

211–220 of 258 posts

Re: API Practices If You Hate Your Customers

#211

Post by mleonhard »

jayd16 wrote: post #164
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 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.

Re: API Practices If You Hate Your Customers

#212

Post by yardstick »

lazyasciiart wrote: post #179
yardstick wrote: post #169

Earlier quoted context omitted.

If under your suggestion you have to look at the details of a 404 anyway to get a detailed error message, what is the point of the 404? Your client always has to do an explicit check for error/no-error. Why make them check two different locations? Just always look at the body: one location.

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 incorrectly think the voucher doesn’t exist, when it does.

If using the other approach, you have this code in the body, you would know straight away that the URL itself is wrong because you’d have no JSON body.

So in the former approach the client code would be oblivious to the error until someone realises, maybe years down the track, that the code is calling the wrong URL. In the later approach you would know immediate as the client will receive a body content it’s not expecting and throw a fit.

Yes you could return 404 as the http status code and embed the code into the body, but that brings us back to why do both? That opens up for lazy programmers to just check the first and not the second.

Re: API Practices If You Hate Your Customers

#213

Post by afiori »

ergothus wrote: post #111
kelnos wrote: post #101

Earlier quoted context omitted.

Responding politely could also teach the junior that it's ok to act like an asshole, because he'll get a polite response no matter what. I suppose the ideal response would have been a polite correction, followed by a polite rebuke regarding the junior's tone and behavior, but I can't fault someone for responding to fire with fire on occasion.

A polite response does not have to be a meek response. You can be blunt, you can point out all the problems, while still being polite. That also has the advantage of being 100% clear. "You just told hundreds of people my code is poor. You attacked me, and my professional reputation, and you did it inaccurately. This gives me little reason to respect you or want to help you. Asking without copying the world and withou…

There is also a difference between teaching and grandstanding; the reality of the situation is that there is no single correct response for this kind of situations: the junior maybe was zealous, maybe he was trying to shame the senior, maybe he just copied in CC the wrong mailing list.

Obviously the original answer was not appropriate in every situation, but also likely it was appropriate in some.

Re: API Practices If You Hate Your Customers

#214

Post by avip »

#DJI

Re: hiding docs:

Luckily, this can be easily done by putting the documentation behind a login screen... consider making your documentation a PDF file...

DJI's release notes for the DJI-SDK are only available for DJI registered developers. As a zipfile - of a single pdf doc.

Re: API Practices If You Hate Your Customers

#215

Post by lowercased »

sopooneo wrote: post #138
gtsteve wrote: post #44

Earlier quoted context omitted.

That's fair to say I guess - but it should be accompanied by some other property to indicate a condition like that. The API I'm thinking of though was effectively a wrapper around a database query which retrieved items. That's what gets me about that decision you see. When you get nothing from a database, you get an empty set. The runtime was some version of .NET Framework, which by default would write an empty set a…

I've seen this happen due to system evolution. At first some entity may have a parent record or not. So when you ask for the parent, you either get it, or null. But then the system evolves to not be many-to-one, but many-to-many. To avoid breaking old clients, they make it so the only difference is when they return multiple related records, in which case they're given in an array. Thus you now have: null for empty, t…

there are still evolutionary justifications which I'm sympathetic to now and then, but mostly not. In many (most?) cases, understanding if something should be one-one or one-many is known up front. Or should be known. We have decades of examples of best practices with many common data structures. Hard coding a customer account to only ever have one address, for example - no. I don't buy that justification - a customer/address thing - for any size company/project - should just be modeled as one-many (at least). It may be slightly more 'work' up front, but that work avoids potentially major breaking changes and work later on.

I get countered with "YAGNI" now and then, but after 25+ years of doing this (and, again, decades of examples of your exact use cases already in google ready to learn from), I can usually tell when you ARE going to need it.

Re: API Practices If You Hate Your Customers

#216

Post by lowercased »

ergothus wrote: post #74
dx87 wrote: post #34

Earlier quoted context omitted.

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.

That's the DESIRE for what the junior learned. But is that what they actually learned? One could just as easily (or more easily) decide instead that this is the way business is done. It's literally all they've ever seen.

There's no way to know in advance what someone will learn from an experience. You also don't know what they learn 'now', and what they might reevaluate and relearn years from now about that same situation. Basing your response decision primarily around what someone might learn isn't a great way to decide how to respond.

Couple folks I'm working with right now, and I had thought a couple of times "well, this wasn't a great scenario, but at least they'll learn ABC from it". One did, one didn't, and keeps making the same moves (I hesitate to say 'mistakes', but in my view they are).

Re: API Practices If You Hate Your Customers

#217

Post by saw-lau »

irishsultan wrote: post #185
saagarjha wrote: post #12

Earlier quoted context omitted.

> What do you dislike about that result, and what would you prefer to see returned? It’s inconsistent and means I need to write special case code to check for it, when before I could choose to. It should return an empty array.

null array sounds like it's an array (presumably an empty one), it would have been clearer if OP had said null instead.

Not sure why you're getting downvoted - that was how I read it as well.

Re: API Practices If You Hate Your Customers

#218

Post by nurettin »

hermitdev wrote: post #18
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 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…

How did your API endpoint signal internal errors or parameter errors to the client?

Re: API Practices If You Hate Your Customers

#219

Post by Xelbair »

bouke wrote: post #203
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 the pleasure of working with the API of a customer that wanted to expose a JSON/REST API to their existing XML/SOAP backend. Instead of going the sane rout and re-use the XSDs to serve as the structure for the JSON, they just made the JSON structure up on the go. One child node? That would be one JSON object / value for you sir. Multiple child nodes? That would be on JSON array for you sir. No child node? No JS…

That sounds like absolute nightmare - at least keep a convention.

Re: API Practices If You Hate Your Customers

#220

Post by raxxorrax »

paulddraper wrote: post #54
tbirdz wrote: post #24

Earlier quoted context omitted.

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…

Live by the sword, die by the sword.

Everyone dies from trying to dereference empty vectors that are != nullptrs at some point in their life. It isn't only APIs that can set traps...

Many people don't see mailing everyone as self promotion for showing off, most often they just don't know whom to address with stuff like this so they try shotgun mailing.

That alone can still be bad though, since it gives every recipient an opportunity to be distracted if they want to be.

Post reply on HN