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
. 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
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
loads on your infrastructure. Plan your scaling in advance.
PS: Why I personally prefer delimited strings to XML / JSON? Because they make
understand the system better and read the docs.
That's the reason why I never use delimited strings in external APIs.
November 3, 2016