Relax joy instead of frustration in development teams 6 tips for a user-friendly API design
A guest post by Bear Douglas *
Poor API design wastes resources and can become a real burden for businesses. Avoid unnecessary frustration with six API design principles. Slack has some tips for user-friendly API design.
providers on the subject
1. Less is more
In many cases, interdisciplinary and bundled problem solutions can be useful and appropriate. When it comes to designing APIs (Application Programming Interfaces), the exact opposite is true. For developers to enjoy using APIs, they must be understandable, easily scalable, powerful, and secure.
It is therefore advisable to focus on a specific use case when designing an API – and to define this clearly at the beginning of the development. Existing, complex APIs can also be subsequently converted to simpler, more focused APIs.
2. First impressions count
When you first encounter a new API, it is important that it is understandable and allows for a quick and easy start. A “Hello World” exercise allows developers to familiarize themselves with it within a reasonable amount of time. Experience has shown that 15 minutes before the first API call is a good guideline. Using the “Time to First Hello World” metric, a measure of how long an initial call to the API should take can be given.
How long is actually appropriate ultimately depends on both the platform and the developers’ experience. This experience must be measured not only by “Hello World”, but also by additional parameters. For example, how many users have access to the app.
3. Consistency at all stages
Any good API requires intuitive consistency. A common thread that helps consumers understand an API without reading the documentation. That means: The features that developers already know from an API should be able to be expected even with everything that is still unknown. It is important that this runs through all parts of the API – such as name, endpoints, input parameters and output response. Three phases should be considered:
- Compliance with industry standards: Best practices accepted in the respective industry should be used as a guide.
- Product compliance: Field names should be adapted to the product. Prefer long names instead of abbreviations.
- Compliance with known API methods: Names of known methods must be retained throughout.
4. Meaningful mistakes
Boring troubleshooting? Before development teams do this, they are likely to give up in frustration. Errors should be given the necessary attention well in advance as it can shorten time consuming and subsequent troubleshooting.
APIs should return meaningful, concise, and understandable errors. For example, developers can work much better with the “name_for_long” error than with the “invalid_name” error. A small but not to underestimate difference that helps solve a problem quickly.
Additionally, detailed error forms can be added to the documentation or elsewhere in the API response that provide error descriptions, troubleshooting instructions, or links to more information.
Poor design, poor performance
Not all developers necessarily use an API in the same way. One application generates small datasets, while other API calls can return thousands of items.
In the end, poor design can also affect performance. Therefore, when developing an API, the following points should be considered so that the API can be used individually:
- Large result sets must be numbered consecutively. This avoids overloading the backend of the web application and slowing down clients that cannot handle large amounts of data.
- Accumulation of large joints should be avoided. In this case, numbering is too complicated.
- The speed of the API should be limited to prevent the application from crashing. Speed limitation limits the infrastructure and increases the reliability and availability of the application.
6. Incorrect changes
With product updates, changes to the API are inevitable. But what worked yesterday should still work reliably tomorrow. So what must not happen are wrong changes that damage the customer’s code and lead to applications no longer being able to be used.
If drastic changes are made to an API, do not do this easily or too quickly – in the interest of the developer. Innovations should be announced well in advance to ensure that the process runs as smoothly as possible.
Developing your own API style guide can not completely prevent you from making the wrong decisions. But it helps to define and communicate decisions openly, honestly and clearly. What if a wrong change has crept in that cannot be undone? Then a good communication plan can help – including an apology.
The importance of APIs should never be underestimated. These six tips provide an ideal basis for creating a user-friendly API design that meets developer expectations and avoids unnecessary frustration.
* Bear Douglas is Director Developer Relations at Slack.