We already published a lot of blog posts and successfully held a couple of workshops regarding the very popular topic: APIs. As you know, they’re a crucial part of every digital transformation as we can use them to connect and integrate many different kind of systems and / or devices. In this post I would like to note a few important topics that will help you to build better APIs.
Make it easy to sign-up and to get started
Unless you’re the owner of very popular business platform and there are thousands of developers waiting to interact with your system, you should make your API easy to understand and provide a quick way to sign-up. That means you should provide authentication over popular social networks like Google, Facebook, LinkedIn and of course GitHub.
Make it easy to speed up. Nobody wants to write 200 lines of code just for a simple “Hello World” example. Developers are busy and nobody will watch your one-hour video tutorial.
Documentation is (almost) essential
In my career I’ve never met a developer who likes to write documentation. Bad luck for us, but it is a very important part of every software, especially when we’re speaking about APIs. You need to provide as many useful resources as possible. Yes, I’m talking about examples. Don’t hesitate to invest time to write good examples. Sometimes it’s much easier to understand from examples then from raw technical documentation.
Everybody hates bad, outdated, useless documentation. Use Apiary, Swagger or something similar to follow standards. Your users will appreciate that.
Make it even easier
If you are a really serious player, consider to provide SDKs for popular programming languages. Sandbox Environment is also nice to have. If that’s too much, you can at least provide some dummy data, like the credit card numbers, coupons etc. for testing purposes.
API Design
Consider this as a religion. Learn the REST Specification. Pay special attention to plan and to design good APIs. Make sure you covered all necessary features of your platform.
Think (at least) twice before you assign a name to your endpoint. Make it as simple as possible.
Do not design your APIs with only one application (implementation) in mind. Make it generic and universal.
HTTP responses are very important. Learn to sing this like a song. For example: do not send 200 OK when for NOT FOUND use case. If the request is bad, be polite and say what is bad. In other words, feel free to invest in error messages. It’s also nice to make them multilingual.
Reliability
Do your best to make sure your API is reliable, fast enough and bug-free. Use proper versioning. Nobody likes slow and inconsistent APIs.
Security
Introduce SSL and follow the best practices regarding this topic. Try to use standard solutions and avoid custom-made stuff here. Security is really complex topic and it’s out of scope of this blog post. Make sure you understand what those words means: Authentication, Authorization, Federation, and Delegation. Also, you should be familiar with OAuth 2 and OpenID Connect at least.
User is a king
Do not spam people when they sign up, they’re just developers and your API is a feature, not a product. Respect your users. Today is everything about marketing and making money, but in most cases you shouldn’t spam them with your cool offers.
Listen to your users and consider their feedback seriously. Perhaps you can use your own system without APIs, right? Well, they can’t. You need them just as they need you.
Maintenance
Improve your documentation, fix bugs, update the APIs to follow the progress of your platform.
API Management
Sooner or later you’ll need to manage your APIs on a professional way. This is also very complex topic which is out of scope of this post. I encourage you to try the API Management solution from WSO2.
