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

111–120 of 258 posts

Re: API Practices If You Hate Your Customers

#111

Post by ergothus »

kelnos wrote: post #101
ergothus wrote: post #74

Earlier quoted context omitted.

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.

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 without assuming you were flawless would have done a lot to help your case. Because I AM professional and you are new to the profession, I'll hold back on the reflex to point out to every one of these hundreds of peers that influence your career how rude, presumptive, and WRONG you were. Instead, I'm pointing out in private that you are wrong and not behaving in a way someone looking to succeed is behaving. This tolerance is not something you should expect from me again, and you should be grateful to be getting it now because your behavior does NOT call for cooperation. If you do this again, the next person will likely not show this patience and understanding. Do you understand that you made the error in your code? Do you understand how your behavior invites people to think poorly of you? Do you understand how to change both your code and behavior for the future? "

This has the senior developer takes on more work instead of a sense of vindication. However, this is much more likely to get a positive result in the long term - there's no mystery hope that someone that clearly missed out on social repercussions will suddenly understand them when attacked.

Being a senior developer is not about winning battles, it's about learning to win without battles, and even more importantly, it's about TEACHING that.

Re: API Practices If You Hate Your Customers

#112

Post by WrtCdEvrydy »

ergothus wrote: post #79
akurtzhs wrote: post #5

Earlier quoted context omitted.

returning a null array to represent no items To be honest, that's what I'd expect. What do you dislike about that result, and what would you prefer to see returned? Jump straight to 404? returning a single object without an array to represent one item. So an array if there's multiple results, and a bare object for a single result? That's unpleasant.

> Jump straight to 404? That's my pet peeve. I completely understand the logic - using the HTTP status code to show the result of interaction with the resource is very RESTful - but my complaint is that unless you provide more context, a 404 doesn't tell me if I'm getting a response of "that resource doesn't exist" vs "you're accessing a url pattern that will never work". So if you want this random internet user to b…

We have only one pattern like this... when there's a client resource (containing personal information for contacting them) that the client has asked to be private... we return an empty JSON object (versus an object with the contact information keys)

Re: API Practices If You Hate Your Customers

#113

Post by dullroar »

Here's one from a vendor I currently integrate with - have multiple APIs (in this case, a SOAP one, a REST one returning JSON, and then some language SDKs that wrap the latter for convenience), and have their feature sets be an interesting Venn diagram with various intersections but no unions. Just today I found out that the in the extensive integration we've written using the SDK (which wraps the REST API, remember), I will have to shell out and use SOAP because one (1) parameter on one (1) object in their extensive object hierarchy isn't supported by REST or the SDK, just by the SOAP protocol. Nice.

Re: API Practices If You Hate Your Customers

#114

Post by WrtCdEvrydy »

compscistd wrote: post #17
chihuahua wrote: post #9

Earlier quoted context omitted.

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

This makes sense now. If I did a GET to posts and got a "null", I would think I made some kind of error. If I get an empty array, I would (correctly) assume there are no posts yet. Basically, GET to posts would always return an array of posts. Whether there are 0 (empty array), 1 (just one object in the array), or many (array with n length). This makes API logic way easier to handle without having to check what struc…

Also makes a lot of iteration easier... just a for loop over the array to dump something on the page with no edge cases.

You can add a warning by just checking the length against that array blindly.

Re: API Practices If You Hate Your Customers

#115

Post by WrtCdEvrydy »

skunkworker wrote: post #86
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 that when I was dealing with the Withings API. Oh you got a 4XX error? Here is a 200 back with a json payload of {error: 400, message: "Some message"}. Ugh it was frustrating.

So I wasn't wrong. I fought someone over this and someone else was like 'looks okay to me'...

Re: API Practices If You Hate Your Customers

#116

Post by thaumasiotes »

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.

> XML can’t model single item arrays versus single objects. They look the same.

    
      
        value
        ...
I don't really see the problem.

Re: API Practices If You Hate Your Customers

#117

Post by Ididntdothis »

thaumasiotes wrote: post #116
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.

> XML can’t model single item arrays versus single objects. They look the same. value ... I don't really see the problem.

You need to know that “results” is an array so you need the schema. In JSON an array is an array without doubt.

Re: API Practices If You Hate Your Customers

#118

Post by lapnitnelav »

>"APIs also permit customers to use a lot more of your product. If they have to click, click, click to use your product, they're going to use it only a little. If an API exists, they can automate their use of your product, which would let them use it a lot more. They could automate provisioning for their entire company. They could build entire new applications based on your API. Just think how much more of your product they would be able to consume with an API."

This so much. One of our main adtech vendor is lagging behind on the API front. We've been chasing them for a while on when they'll be up to date so that we can build on top and they get back to us on how their other customers don't really want an API.

Of course, no one (beyond us tech crowd) goes to bed thinking oh I need an API to interface with my DSP. But I'm sure they'd be delighted about what the API can enable them to do.

Here's an advice if you are building / improving a pretty consequent SAAS product : Your UX sucks. Not that it is awful but it is likely not optimised for what your customers are doing, simply because you keep adding features and now it's bloated.

And I don't mean that it is an awful thing, it is the nature of such product to keep growing, because marketing, justifying salaries and obviously adding value.

Chances are, 80% of your customers are only using a good 20% of the features you offered and they'd rather have something that is tailored for efficiency to address their main pain point. So either you step up your game to offer that flexibility or you get your API game up to speed. Your competition might beat you to it and I know which product I'll choose.

Re: API Practices If You Hate Your Customers

#119

Post by thaumasiotes »

scarejunba wrote: post #96
shantly wrote: post #61

Earlier quoted context omitted.

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

I've noticed that if you stay strictly professional, folks think higher of you and they feel shame for having done this. You also appear way wiser and likeable - all of which gives you more clout. And if you're more often right than your peers, everyone benefits by your having more clout. I've been in this situation before and I've found this approach beneficial.

http://www.basicinstructions.net/basic-instructions/2012/11/...

Re: API Practices If You Hate Your Customers

#120

Post by kbenson »

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…

Really, there are many reasons to run internal mailing/distribution lists and designate emails from them in some manner, such as a subject prefix. One of which is that people are less likely to sent an email to the "Staff" list if most the correspondence there is from management and about company level things, and then it's also very appropriate to reply to the email with content that addresses the request (in this case, you're wrong, don't do that) and also a rider about how this is not the appropriate place for this, and they should submit to the appropriate list/form.
Post reply on HN