13
haze
6d

This is the story of the API documentation.
Which btw I couldn't find on the producent's website anywhere. I had the pdf shared with me by a coworker.

I knew the api was fucked up the moment I looked at endpoint documentation.

GET params? WHERE, ORDERBY etc. Literally make a SQL select in a GET request.

Returned stuff? The whole thing. Not some DTO, you literally get everything you can get.
Eg if you get IP in your response, you get it in several formats: dotted form, as hex, and as int. In 3 different json fields.

Oh, and regarding IP - one would imagine you can use masks or prefixes for subnets, right? Nope. The only param you can use there is the subnet size. So you have to calculate the power of 2 every time you want to make a request.

That's from the endpoint documentation. But what about some general info on the API, before all that?

As I was looking for something, I decided to read that intro and general info about the API.

Okay, so there was a change log between API versions. "removed [endpoint which sounds like correct REST design], please use [this generic thing with SQL-like GETs]"... Several of them.

And there was also this sentence which said that the API is not restful, "it's REST-like". <facepalm>

If it was a bad attempt at REST API, I would let it go. But this sentence clearly showed they knew they did everything wrong. And the changelog showed they didn't stop there, they were actively making it worse.

Comments
  • 6
    On the producer's website, there are several big clients listed. You know, that kind of advertisement "those reputable orgs use us". It's scary how many big companies and universities use that bad product.

    Or maybe it's because the product itself isn't that bad, just the API... And I assume you can't see API documentation before purchasing (as I said, I couldn't find it anywhere, coworker probably got it from our client).

    So the problem only starts when you have to dig in the API. When it's already too late.
Add Comment