How to make an API?

Background...

For a few years I worked with different APIs delivered by the different vendors. I was also taking part in designing and creating of the APIs for the software that I was working on. In this post I would like to describe some key points, which in my opinion a good API should have and some that shouldn't have.

Subjective list of the well designed API features

• Extensibility

  Remember, to make your API extensible. It is more than possible, that you will need to add some new features as a client request and it is better to do this as fast as possible, especially if your system and the API are new on the market.

• Batches

  Your API should offer a possibility of using batch operations. E.g. Taking details of an object can be done either for a list of items, or only for one of them. It will decrease the number of hits to the server and increase performance.

• Technologies easy-to-use

  Try to avoid old, complicated technologies. If you can give an access to your system using the REST service, then use it instead of the old web service. If you are designing a desktop application API, then don't use old, awful COM objects, when you have many different ways of accessing the data.

• Return everything as a result

  This point may be controversial and I am sure that not everybody will agree with me. I think, that the best way to return any data is to return it as a defined result type. The worst thing you can do, is to throw an exception every time something unusual is happening, instead of giving the user a possibility to decide, what he wants to do. Remember, that this situation may be unusual, but it might not be an error in your clients system.

• Meaningful error messages

  If an error appears, do not return only the code of the error. I know it is the easiest way, but not the best one. Nobody likes receiving only the number instead of the message.

• Meaningful names of types and methods

  Names of the methods and types should be simple and meaningful. If you are not sure, if the name is simple enough, it means that it is probably too complicated and if you are not sure, if it is meaningful- ask someone who is not working on this project, what in hers / his opinion this type or method is created for.

• Well documented

  I know, that it is not possible every time to make a good API documentation, but if you have some time try to make some documentation. It would be a great help for the users of your API and more people will be willing to try it.

• Supported by the community

  If you have a support, it is much easier to use any API so think about making a forum, Facebook fanpage or any other place, where users of your API can exchange their experiences, ideas and ask questions. Remember, that many interesting projects failed because of the lack of community support!

The most common problems

• Old technologies

  Sometimes developers can design a useful API, but finally they are trying to rebuild the old version of API using old technologies. If it is possible, try to make a new API and show to your clients, why it is better to use the new one. Remember- do not to give access to the old API to new clients- it causes problems.

• No support

  API must have a support: either paid or community (free) - this is obligatory. If there is no support, then nobody will even try your API.

• Not enough tests

  Always give your clients well tested product. If API contains errors, then it is not reliable so nobody will trust you and your API.

Things to remember

• Listen to other developers

  Even if your API is the best in the whole galaxy, maybe it is worth to hear other developers opinion. They sometimes may have good ideas, which may help you in creating really great API :)

• Listen to your clients

  Client is a boss. Don't forget about it. If he is saying that something might be better or easier to use - think about it and try to understand clients' needs.