Jacob Baytelman - Full stack developer, project manager, CTO

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. Don't 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.

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 3, 2016