Let's Build an API Together - Part 17

11.01.2018 by Jens in API Series | APIs | Newsletter

When we return error messages, and along, we should not expose too much information. Same goes for normal data. More, especially detailed is not always better. It depends on the type of API and what the clients do with it and who the clients are.

If you develop internal applications, it is probably not that important. However, if you have an external API for the masses or partners, it looks a bit different.

One of the details we should limit are security related things. The classic login screen is a good example. If I enter a wrong username, many apps return a detailed error that there is no such user. It is helpful to me as a user, but it also helps potential attackers to guess usernames.

Same goes when a dev has the urge to expose user roles in the API so a client can check something. Things like roles and privileges should mostly stay on the server side. It is also common that dev exposes too many details in a JWT because they forgot that it just signed, not secretly encrypted.

Besides security, there are cases where too much detail is not helpful for a client or user. One case would be errors in the infrastructure. It does not help the user when he gets a warning that his task could not be saved because a queue or whatever was not available. A simple, “sorry something went wrong in the backend, yadda yadda” is enough.

What I also see here, is that when we are too verbose, the business logic could be re-engineered. That can be problematic in cases where the logic is the gold and not the data.

Start with a dumb version and then expose new details slowly as needed but keep an eye on the risks.

Want content like this in your inbox each workday? No BS, spam or tricks... just useful content:

I understand and agree to the privacy policy