Jacob Baytelman

Building software since 1998

Innovations of Tomorrow Projects Contact me

The best things you can do when creating an API

Firstly, go an see how other APIs in this industry are implemented. Try to analyse at least 3-4 leaders, savour their best practices and reproduce them.

Secondly, think about people who will integrate your API. Provide decent documentation and EXAMPLES. Do not expect other developers to go deeply into detail of your system. They need simple and quick ways to integrate, so give them examples ready for copy-pasting. I would even go as far as saying that if you provide good examples, the rest of the documentation has almost zero importance.

Create a test sandbox and make it easily accessible. Also, make sure that transition from the sandbox to production is as easy as changing of one single parameter.

Follow the minimalistic data approach, don't request and don't return unnecessary stuff.

Be crystal clear as to your access restrictions and permissions. Explain them, return meaningful error messages, so that a developer would not struggle with "a bug" if it's your limitation.

SOAP or REST? Do whatever is easier and more convenient for your users, not for you :) Remember, there are alternatives to both REST and SOAP.

Keep in mind your system security and loads on your infrastructure. Plan your scaling in advance.

PS: Why I personally prefer delimited strings to XML / JSON? Because they make my developers understand the system better and read the docs. That's the reason why I never use delimited strings in external APIs.

J.Baytelman November, 2016