In this post we will see 10 important things to keep in mind to set-up an effective developer portal and some tips about Azure API Management
#1- Explain your offer
Keep it simple, explain the value of your APIs in a clear and compelling way. The home page of the dev portal should provide a clear answer on “what are you offering” without struggling to figure out what the API does. Another question to be answered is about what can be built with the API. Hence also consider the opportunity to create a section dedicated to the use cases.
APIM tip: APIM comes with a full CMS with a high degree of customization. Plan your dev-portal concept and leverage the CMS creating additional pages, sections, custom assets, and introducing different style layers.
#2 – Developer On-boarding
The on-boarding procedure through which a developer gains access to the API must be intuitive and easy. The developers want to be productive quickly and be able to try-out your API in minutes. In order to speed up the on-boarding process, enable different identity providers like Google, Microsoft and Twitter.
APIM tip: If feasible, evaluate to add the possibility to try-out your APIs or part of them without registration. This is a nice to have. I don’t want to register and have a key for every API I want to try.
#3 – Getting started
Again, the developer portal is all about to enable the developers to hit the ground running on day one and be productive immediately.
It’s mandatory to provide a tutorial that guides the users through the authentication process and how to perform the API calls via the SDK or directly from code. Those tutorials should be not limited to simple calls and it might cover complete use cases like the “User-Registration” or how the “eCommerce transaction” works. Keep in mind the type of audience and their preferences.
APIM tip: Create a dedicated page/section and link to this section directly from the home page.
#4 –Add discoverable metadata endpoint(s)
Nowadays there are different formats to describe an API. Swagger (reborn as OADF with the Open API Initiative) is the de-facto standard but others like API blueprint or apiary are emerging.
Publishing metadata endpoints with different formats can help the intake of our API. Consider to use the swagger json as the input for the apitransformer tool to generate api blueprint and raml. The downside is that you have to mantain those different outputs.
Description languages are great integration enablers, but don’t forget that the most effective documentation is the one written by humans.
APIM tip: APIM provides the swagger and wadl definition in a secure way via the admin portal. The disadvantage is that we cannot virtualize it to make it discoverable. Consider to download the swagger json file and I re-published it in the dev portal.
#5 – Explain headers
HTTP headers are used for multiple purposes, such as describing the media-type of the exchanged entity, managing the versioning or, for example, as transaction parameter. There are headers that are applicable only for the requests and others only for the responses. Headers that have a generic applicability and headers that are bound to the resource we’re requesting. Standard headers and custom headers.
In this jungle it’s easy to lose your way.
It’s important to describe all the mandatory headers and their applicability, what is mandatory and what is optional, the value that we can expect in the response and how to use it. Use a standardized approach and don’t document the same thing multiple times.
APIM tip: create a custom section dedicated to the headers and customize the operation template to create a link to the headers’ documentation to accessing the extensive description.
#6 – Explain authorization and authentication
There are several way to implement authentication and authorization in RESTful context. OpenID connect, basic authentication, shared access key, certificates, asymmetric keys are some examples.
Some of those are implemented using headers, others with different mechanisms. No matter which type of AuthN/AuthZ you adopted, you should explain in detail the model you are using and how to get the access codes.
APIM tip: It’s recommended to have a dedicated section about authentication and authorization.
#7 – Status codes, example of requests and responses.
A proper documentation not only helps to perform the API intake but it’s a key factor to retain the developer. Pay attention to enrich the API reference with request and response documentation for all the functionalities you provide.
APIM tip: APIM provides out of the box the possibility to add different status codes with different representations. It’s a matter of configuring and keeping it in sync with your API versions. All this information is displayed on the “Operation details” page.
#8 –SDKs, code samples
The aim is to provide developers the tools to easily connect to your APIs. Code samples and SDKs are the pain-killers for every API intake especially when your API is dealing with complex data structures and binary objects.
On the other hand, building an effective SDK and libraries in multiple languages may require a huge investment, especially for a public API that also targets mobile devices.
APIM tip: APIM provides the code samples to directly invoke the API in different languages. Use the “code samples” template to customize the way the code is generated. Publish all your libraries and SDKs on GitHub. If you’re targeting .NET shop, autorest is a good choice to generate client sdk.
#9 – Support page
The goal is to provide a great developer experience, preventing loss of productivity and customer frustrations. Configure a central point to organize your support service to address the problem right away. The support can be delivered over the phone, with a live chat, a ticket system, social networks and many other ways.
APIM tip: Issue management out of the box can be combined with custom pages to organize other channels (email, social networks, etc)
#10 – Communication and Change log
Attract, engage and retain external Developers, Consumers and the community in the business maturity by establishing an effective and open communication through the API Developer Portal. Provide a tool to discuss your product (and your documentation), provide feedback and feature requests. Create a section to collect the latest news about your API, articles and, last but not the least, to publish the change log.
APIM tip: A blog is a great source to deepen the connection with the developer community. Consider to activate the blog feature and enable the RSS feed to automatic data syndication. Put your documentation on github to facilitate the external contributions.
Conclusion
It’s all about providing a great Developer Experience. Give to your API a compelling front door and boost the API to success!
Cheers,
Massimo
Subscribe to our RSS feed