Also, certain websites would have a huge amount of traffic, and blocking them from using the API just because of that without any warning might make developers move away from such a system.
Please, be specific when making such guidelines and think about the users when coming up with rules like these.
Sin 6: DocumentationThis is how the API documentation looks like:Beds24 API documentation look&feelThe only problems here are readability and overall feel.
The same documentation could have looked way better if the author would have used markdown instead of custom non-styled HTML.
For the sake of this post, I created a better version with the help of Dilliger in under 2 minutes.
Here is the result:Styled version of the documentationPlease, use tools to create API documentation.
For simple docs, a markdown file like the one above can be enough, while for larger and more feature-rich documentation, tools like Swagger or Apiary are better to be used.
Here is a link to the Beds24 API docs for those who want to have a look at it themselves.
Sin 7: SecurityThe API documentation states the following about all of the endpoints:To use these functions, API access must be allowed in the menu SETTINGS >> ACCOUNT >> ACCOUNT ACCESS.
However, in reality anyone can make a request to fetch data without passing any credentials for certain calls, like get availability of a certain property.
This is stated in a different part of the documentation:Most JSON methods require an API key to access an account.
The API code can be set at the menu SETTINGS >> ACCOUNT >> ACCOUNT ACCESS.
In addition to the miscommunication about authentication above, the API key is actually something that the user needs to create themselves (actually type the key manually, no autogeneration whatsoever) and it should be between 16 and 64 characters long.
Allowing the user to create the key themselves could potentially lead to very insecure keys that can be easily guessed, or certain formatting issues since any string can be entered in that field in account settings.
In worst cases, it could also become an open door for SQL injection or other types of attacks.
Please, never let the user create API keys.
Always provide them with immutable autogenerated keys instead, with an ability to invalidate it when needed.
For those requests that are actually authenticated, we have a different problem: authentication token has to be sent as part of the request body as seen below (from documentation):Beds24 API authentication exampleHaving authentication token inside request body means that the server would need to first parse the request body, extract the key, perform authentication, and then decide what to do with the request: execute it or not.
In case of a successful authentication, there is no overhead involved as the body would have been parsed anyway.
In case authentication failed, the server did all the work described above just to extract the token, spending precious processing time.
A better approach instead would be to send an authentication token as a request header, using Bearer authentication scheme or similar.
This way, the server would only need to parse the request body in case of a successful authentication.
Another reason to use a standard authentication scheme like a Bearer token is simply because most developers are familiar with it.
Sin 8: PerformanceLast but not least, it would take on average a little over 1 second for a request to complete.
With modern applications, such delays may not be acceptable.
Therefore, take performance into account when designing APIs.
Despite all of the issues with the API explained above, it does the job.
However, it takes several times longer for developers to understand and implement it, as well as forces to write more complex solutions to trivial problems.
Therefore, please think about developers implementing your API before releasing it.
Make sure the documentation is complete, clear and well-formatted.
Check if your resource names follow conventions, that your data is well structured, easy to understand and use.
Also, pay attention to security and performance, do not forget to implement error handling correctly.
If all of the above is taken into account when designing an API, then there would be no need for weird “guidelines”, like in the example earlier.
As already mentioned, the goal of this post was not to make you never use Beds24 or any similar system because their API is not implemented correctly.
The target was to increase the quality of software products by sharing a poor example and explaining how it could have been done better.
Hopefully, this post would make someone pay more attention to software development best practices and make software systems better.
Till next time!.