TL;DR notes from articles I read today.
Best design practices to get the most out of your API
- You should design your API in a way that it does one key thing really well. Don’t try to add too many what-if scenarios.
- Make your API easy to understand and fast to start up.
- Aim for intuitive consistency with repeating patterns and conventions in endpoint names, input parameters & output responses so that developers can begin without reading the documentation.
- But still, create great documentation. And let developers try your API without the need to log in or sign up.
- Make troubleshooting easier by returning meaningful error messages.
- Make your API extensible with primitives that enable new workflows. Include an opportunity for feedback from top partners - perhaps allow few developers to test-drive beta options.
Full post here, 7 mins read
What’s the difference between versioning and revisioning APIs?
- Look at release management as a communication tool - to and for your API consumers. You can take two approaches to it - versioning and revisioning.
- Versioning implies that each group of related changes in an API is presented under a specific number, often denoting the type of release.
- Revisioning implies incremental changes have been made and it prevents version-to-version code breaks, allowing legacy code to continue functioning.
- You will find versioning useful when your API is flexible enough to support version 1 as legacy while transitioning to version 2; or when your API is only useful as a conduit to another API or system.
- Revisioning is a more apt approach if your API supports vital business functions, medical purposes, security systems, etc., where it is essential for the API to stay up and running at all times.
Full post here, 7 mins read
4 ways your API specification can fall short and what to do about it
- You should communicate clearly about the number of items and pages developers can expect from each endpoint so that developers don’t make assumptions about it.
- Your spec should clearly state the size constraint for each response developers should keep in mind while coding.
- Your spec must set a performance standard and stick with it because developers code for their applications using your APIs after considering how fast/slow your APIs return requests.
- Cover authorization extensively in your specs. Encourage the use of refresh tokens throughout your documentation.
Full post here, 5 mins read
Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().
Top comments (0)