Gael is an API Product Manager with Amadeus. In this article, he discusses releasing APIs for developers.
For an API, documentation is very important. Try and use your documentation like a developer would.
Nowadays, very often, the tool you’re using to design your API is completely different than the one you’re using for your user. That can lead to some discrepancy in the markdown or even in the declaration of some models. So, double-check the documentation.
The next tip is to use tags. Tags are used to regroup endpoints that are working together. Tags can create a unique experience for your user and guide him through the easiest path to learn about your API.
Another tip is to add a working example. This is helpful to reduce the time for the first API call. The developer will love to use this feature and get a shot at the API before reading the documentation.
Finally, when you release multiple APIs, ensure you maintain consistency. Try to be consistent in the way you’re entering your error, creating your models and your parameters. The key here is to create a familiar environment so that the time your user invests in one API can be used to learn the entire project.
Now that we have good documentation, the next step to release an API is to start thinking about the conversions and commercials. In a pricing plan, you negotiate everything with your user and customer.
But for OpenAPI, the key is to have an attractive offer to the maximum number of users to use it. The real challenge is to do enough to attract more users but not overload your production environments, which may lead to poor experience for the other customers. To do this, here are a few tips.
The first one is to take your time to choose the API name. The name should make sense, but also let the user know what the API will do.
Secondly, when you’re in doubt, always go for the worst option for your customer. This may sound weird, but consider that you are pricing an API low because you want to attract people but realize that it’s a loss-making proposition and want to increase the price. This leads to discontent amongst customers. So, it’s best to start with a higher price and then reduce if you think it’s the way to go.
The next aspect to think of while releasing an API is the connection. We need to provide a test and production environment to the developers. The developer can test his code, and if happy with the results, he can move the code to live data and production environment.
So we went through all the basic steps of building an API, creating good documentation, defining the commercials, and releasing it into the internet. But we can do better.
The next thing to do is Communication about the API release. The most straightforward is the developer portal, where you can update your changelog. You can add banners, blog posts, newsletters, etc, announcing your API. You can also communicate through social media such as LinkedIn and Twitter. You can participate in communities and events to reach out to more people.
While deciding on communication methods, it is very important to consider your target audience, a developer, a business, etc. You also have to think of your communication release. People may not respond to your emails if it’s a festival season. So, avoid such periods for release.
The next step is building some developer guides. These guides are technical. They can explain and have tutorials related to use cases that the API can address. Tutorials need to be built for all types of developers, irrespective of their proficiency. Developers will comment on these guides and will have questions on the implementation. So, you need to have some resources looking at these comments and replying to them as much as possible.
We can have SDKs to help developers access all APIs, authorization, error handling, and code examples.
For example, in the models for developers, you need to generate an access token with your API key and API secret to generate. It is pretty easy and straightforward. But when you want to refresh the access token, which expires every 30 minutes, the developer will have to build some logic for that. SDKs can help with this.
Try to make your SDKs open-source. Developers love open source, which helps build trust in your community. Another thing to consider is the technology you want to support for your SDKs. For that, maybe you can do some analysis to see the top programming languages being used. Or maybe you can analyze the logs you get in your back end to know what languages developers are using for your API. Finally, it’s very important to have a high-quality SDK that is well-documented and well-tested.
Using these techniques, we have reduced the time for the developer for the first API call.
Now, we must think of ways to continuously make it easier for developers to use and adopt your API.
You can have advanced tutorials, video guides, etc. You can build some plugins that developers will be able to integrate into their applications, maybe without having to write any code or some widgets that are easy to integrate and customize.
And there’s a way to go beyond this by inspiring the developer. When you release an API, you often have to choose one specific use case you’re highlighting. But you can have a visual dashboard showing all the API can do, etc.
To conclude, the article discusses tips to make it easier for a developer to adopt your API by giving guides, tutorials, and consistency in the release process.
