Live data from Hacker News

API Practices If You Hate Your Customers

queue.acm.org

201–210 of 258 posts

Re: API Practices If You Hate Your Customers

#201
> Technique #8: Ignore the IaC revolution

Google Firebase has no API for creating projects. Therefore it is impossible to use Terraform or other IaC (Infrastructure as Code) tool to provision backends that send push notifications to Android apps. Manual steps are required. In this way, Google Cloud prevents its customers from using SRE best-practices.

https://github.com/terraform-providers/terraform-provider-go...

Google as an organization is simply unable to focus on users.

Re: API Practices If You Hate Your Customers

#202

Earlier quoted context omitted.

Not a parse error but a single “result” object, not an array of length 1. With two elements it recognizes an array.

If you can parse and you end up with a single "result" object, you must have identified "results" as being an array of one element so that you could discard it. (You didn't get a single "results" object.) That's not a problem in what XML is able to model, it's a problem with you throwing the information you got away and then pretending you didn't receive it. On the other hand, if you meant that you get a single "resu…

You do understand that php and quite a few other languages provide pre-built serialization and de-serialization from XML, right? The OP was talking about the out of box behaviour for those. Your answer seems to predicate on having written a custom deserializer.

Re: API Practices If You Hate Your Customers

#203
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 JSON type for you sir.

So what happened when the amount of child nodes was dynamic? You would either get: nothing, an object, or an array of objects. Oh the fun times we had!

Re: API Practices If You Hate Your Customers

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

A sample output (either XML or JSON) is not a substitute for a specification.

Looking at the XML when a list has only a single element, you wouldn't know if there could be more. You need an XSD to accompany the XML, which is what is typically provided.

When looking at a JSON document you might run into the same situation where the document you received doesn't contain all possible elements, and you wouldn't be the wiser. You'd still need a proper JSON schema to accompany the document.

Re: API Practices If You Hate Your Customers

#205
post #175

Earlier quoted context omitted.

And since the boss knows you are right because of your previous behaviour, all you need to do is ask the boss to take care of the disturbing element if it continues.

That's making a lot of assumptions about your 'boss'.

Yes I'm aware. I have been extrely lucky with my jobs so far.

Re: API Practices If You Hate Your Customers

#206
post #203
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…

I bet $50 there was a junior dev promoted too high too fast proud of that technical feat.

Re: API Practices If You Hate Your Customers

#207
post #181

Earlier quoted context omitted.

There's often a semantic difference between null and empty. Like, if I'm checking the result of a batch processing job, I want to know if the job finished & resulted in an empty set, or there is simply no result yet. It's "the thing you're looking for doesn't exist" vs. "the thing you're looking for exists, but is empty."

Ehm you shouldn’t GET for the result, but for the job descriptor. If you really need to GET the result then you should expect an HTTP 4xx or 3xx response. There is no justification for NULLs

If your API is RESTful. There are plenty of “rest” APIs out there that are really JSON-based RPC endpoints.

Re: API Practices If You Hate Your Customers

#208

Earlier quoted context omitted.

For those Gophers reading this and sobbing silently, there may be hope: https://github.com/golang/go/issues/27589

Why would you want to marshal a nil slice to json as non-null? That just hides the fact that you had a nil slice. In fact, that's the exact opposite problem; representing nulls as empty arrays.

As explained in the thread, that is because Go best practice is to treat `nil` and `[]T{}` as the same thing in every API. If you want an explicit `null` in your JSON you can use `*[]T` as your field type, and then it makes more sense.

The very idea of allowing the nil value for slices seems to be very strange and inconsistent, as slices are struct types, not pointer types in Go (they contain a pointer and other members). Just one of the many ways that builtin types in Go are fundamentally different from user-creatable types, I guess...

Re: API Practices If You Hate Your Customers

#210
Question: do you guys find a graphql-only API acceptable in 2019? For us to develop a (good) REST API layer on top of our existing solution is a non-trivial piece of work, and GQL offers us all we need on the front end. Customers seem ok with it, but we haven't got any large enterprises yet.
Post reply on HN