Comment by gamache | Hacker News Reader

Comment by gamache | Hacker News Reader

Parent Full thread

No, no, no. I disagree strongly that APIs should be vague about what they provide.

An API designer who deliberately leaves out documentation of important features (like pagination, sorting, etc), and fails to specify the format of what comes back any further than "this will be what you intended", hasn't designed an API at all.

APIs are well-defined interfaces that other programmers can rely on. If there is no well-specified contract, there is no API.

Defining such an interface so that it's reasonably future-proof? Yup, that's hard. And you're not an API designer until you take on that challenge. If you instead punt on all that responsibility, and provide the user few or no guarantees about how your service works, you've taken the cowardly way out.

The essence of software architecture is isolating and tackling complexity. Isolate it in the API, don't push it out to every one of your users.

I don't argue that an API needs to specify absolutely everything about its operation, but obscuring and removing features from an API without changing the version number is foul play. That is fragility.

It is very important to also document what the API doesn't provide, in addition to what it provides.

If the documentation doesn't specify the sorting order, this means that the client must not make any assumptions on the sorting. The client either has to take the sorting as is (and trust the API provider to always use a userfriendly order), or has to re-sort the result on client side to stay in control.

A similar argument holds for the result set: If the API docs specify that there may be "additional fields", the client must be flexible enough to ignore unknown fields.

There is an important difference between being deliberately vague (being clear on what the API doesn't guarantee) and just being vague (sloppy documentation). The latter is of course a PITA, but I it is clear from the article that it's the former what the author had in mind.

Hi Pete,

When I read your comment, I'm left with the distinct impression that we agree on 90% of what you're saying.

Of course you're going to document your API and define the format of what comes back from your requests. An API is a contract. Yeah, you isolate complexity in your API. You design an API, which is a difficult job, rather than just saying to your user, "here's a mapping to my database, do whatever you want with it."

This article does not say that APIs "should be vague about what they provide." It says the opposite, they should be very specific about what they provide.

You design an API by providing specific tools for your users. You give them hammers, not chunks of metal that they can mould however they want. You don't throw "features" into your API, you provide capabilities that your users need.

Mathieu

I think it depends on why you are making the API.

If the intent is to publicize your business by letting other programmers integrate their app/website with your service then I agree with designing an "API" that way. Because you don't want people to do with your API things you didn't intend them to do.

If the intent is to give other programmers the ability to work with your data and create their own thing using your service then the API need to be more flexible and be able to give more freedom possible to the users.

Reply on news.ycombinator.com