An API is the way components and applications communicate and are therefor a major part of any application. An API are not just public methods of a class, it goes way beyond that. Some forms of an API are:
- public methods of a class.
- web calls (HTTP, TCP)
Communication will take a strict form the data must be in order to be valid. For a method this is the method signature while for a database this is the database schema.
Because an API is something that is used by other components or applications to communicate with you, it is hard to change as a small change will require all users of it to change their application as well. This means an API can often not be altered very much after it has been released, only backwards compatible changes are allowed. It can even be argued that bugs in the API can not be fixed anymore as some users could depend on the faulty behavior of the API. In most cases clear bugs however will be fixed, but an alternative and better way will be provided as an alternative for those users. Such a change must be communicated clearly in advance such that users have the time to adapt. It is clear that maintaining an API can be a very hard job.
If an API is that important and it can become such a pain to maintain you would assume that a lot of time and effort is taken to design the API. A clear up front design of an API is however very difficult because the application itself can change in the meantime. Opening up things as you go is often much easier than thinking in ways of a clear design and minimizing the API. But opening things is very dangerous, as once they are available to users they will start using it and you will have to maintain it. Sometimes you can get away by saying it was not public API, and they should not use it, but your users will require at least a substitute for it.
At my previous company, and I can imagine at many others as well we had a public API, which we allowed customers to use, was documented, maintained and guaranteed to keep working with every new release. On the other side we had a private API that was only meant for internal use for our software that allowed communication between components and between different servers. While the idea sounds logical, as you will often grant yourself more rights simply because you know what you are doing, it actually isn’t. What on earth are you doing that you need access to something you don’t want your customers to use? This may be an indication that your application is badly designed and split up in different components.
Moreover, since our private API was only for our own use, we didn’t take the time to document it, leading to a lot of confusion and a lot of effort each time you had to use it. While just adding documentation for this API would solve this, it is still a bad idea to have an API that your customers aren’t allowed to use simply because you can’t enforce this. It is much better to consider all API to be public as there is no reason why your application should do something more than another user should be allowed to do.
Another important aspect is to keep the API manageable. The bigger the API the more work it will be to maintain it. The REST API we had at the previous company was huge. Moreover it had multiple paths to get the same information. An example of this is the user management aspect. Though it was a very simple system, with a user having a set of roles and groups and groups itself having a set of roles as well. A users would have the permissions of all the roles it had either directly or indirectly through groups. This however lead to multiple paths of getting the permissions of a role:
Would all give back the exact same information, if the user and group had the required role. This ambiguity can be simply fixed by cutting of the path to only get the roles a user or group has and letting to user to use the first path to get the information of the role.
The conclusion is that your API is critical for later maintenance, and though designing it up front may not be possible, it is critical to keep it managed instead of just letting it grow out of control.