Consequences of poor API design

A poorly designed API leads to additional work for developers, integrators and operators.

Author: Christian Ludt

If an API is poorly designed, this has far-reaching consequences: Those who use it take too much time to understand it, too much time to use it and make too many mistakes. My field report from everyday life shows how a badly designed API has a concrete effect on the project and the operation.

Not always you have control over the design of an API. If third-party products are purchased, you rarely have direct influence on the development and design of the interfaces. An ipt customer purchased a third-party product that offers a poorly designed, REST-like interface. The following four design flaws repeatedly caused problems during the development of the client and during integration.


The content of the decisive request is structured data. But - contrary to what is stated several times in the documentation - they cannot be validated against an XML schema. The content type is plain/text and the content is a very complex, XML-like structure. The third-party vendor does not offer an SDK or other tool support for this.

Without a formal description - such as an XSD or JSON schema - it is not possible to check requests for correctness. This means that errors are only detected at runtime. This means that lengthy troubleshooting is pre-programmed, development and integration are delayed, and the project falls behind.

Bad, no or incorrect error messages

If the above-mentioned request is now sent with an incorrect content, so that the server does not understand the content, the server returns a general error message: HTTP 500 - Internal Server Error. This means that the client cannot see that it has sent an incorrect request. The server should better send a HTTP 400 - Bad Request to tell the client that there is an error on the client side. In this case, it would also be helpful to specify where exactly the error is located.

Bad, no or incorrect error messages have effects on development and integration as well as on operation. If nobody knows where exactly the error is, in the best case all parties are involved in finding the error. In the worst case nobody will care.

Faulty documentation

Man-made documentation can be faulty. It becomes troublesome if sample requests copied from the documentation do not work. Developers usually try to find the error themselves first and check every bit and byte, be it the possibly wrong content type, wrong encoding or forgotten HTTP headers.

Usually, the thought of incorrect sample requests comes at the very end; by then, several hours have often passed, and in the case of complex requests, perhaps even several days.

No downward compatibility

In a minor release the implementation was adapted to the documentation instead of adapting the documentation to the implementation. This meant that the interface was no longer compatible with the previous version. This meant that all clients had to be adapted.

This API design error is certainly one of the easiest to avoid.


A poorly designed API leads to additional work for developers, integrators and operators. If you are not in control of an API, you have no choice but to live with it. This must be taken into account from the very beginning of the planning process and the unavoidable additional effort must be taken into account. Then even the integration of a poorly designed API will be a success.