.svg)
Mind the Developer Experience
Get StartedEach API has its own set of non-functional requirements. These often cost the most to fix later while being easy to handle in the first design phases. Traditional approaches concentrate on the project or solution level - not single API. The idea is to use the Minimum Viable Architecture approach so we design and build only as robust architecture as we need right now so we can optimize the work, schedule, complexity, and cost
Mind the Developer Experience
Publishing an API does not guarantee it will be used. More adoption of an API may mean more API consumers contacting the support. The Mind the developer experience phase contains ways to ensure your API can be found, tried and supported by your intended API consumers, especially developers.
.jpeg)
Finding the API
Who are the target developers and other API consumers? What are their expectations for APIs? Where do they look for an API?
The future API consumer finds the need for something that could provided as an API. This could be e.g. accessing data, face recognition, turning on the lights or calculating shipping costs. The API consumer then starts looking for internal or external solutions. The API consumer may be e.g. a developer, integrator, architect or business manager.
Research your API consumers. What tools they use? What experience they have? What are their business and technical needs? Use the data to choose channels to communicate and design documentation and tooling. Validate plans with target audience.
Trying the API
How can the API consumer access the API? Is the technical format for the API suitable? Are there any code examples or helpful tools? Is the documentation available and correct?
With APIs, like any software products, it's important to try it out before buying or taking in to use. Depending on the resources that the API makes available this may be tricky. Consider a car API, heart monitor API or a payment transfer API. It's not possible to let API consumers try the API with real devices or data. Often APIs have business logic that needs to be explained in addition to technical use.
Research and validate this with the API consumer segments. Are they using other similar APIs? Are they using the same technical standards? How do they find the API functionality? How well it answers the technical and security concerns they may have?
Using the API
How API consumers can get support? Can they request features or fixes? If they are happy, can they advocate the API to others?
Understand what are the channels and the ways for the developers and other API consumers to get assistance in using the API. No matter what you decide to offer them as support channels, your API consumers might look for support elsewhere.
If all ends well, and the developer manages to solve their coding problem using your API, she may be your best advocate. She might even make tutorials, videos, useful code libraries, or use your API to train others and answer other developers' questions in a community.
What are developers interested in?
Developer experience is linked to both business, product, and technical features but also to marketing and communications
Developer experience is a lot like customer experience. It can have a big impact on the end-customer experience of the API-using application as well. Depending on maturity level there are different aspects to developer experience.
"Finding the API"
" Getting Access to It "
" Compatibility of features to needs, does using the API save time and effort or bring some advantage that you wouldn’t have without using it "
"Knowing what it can be used for "
" Understanding Specifications "
" Sustainability of formats, endpoints and authentications "
" Cost of using it "
" non-functional requirements: latency, reliability, security and error handling of the API to suit the needs of a particular application. "
" Being able to give feedback, knowing about changes, the image, and brand of the company offering the API "
Developer experience design starts when the API is designed with API Canvas. See also API Consumer Interview -template to understand the specific technical needs of your API consumers.
Onboarding Developers
In addition to the API it self, there are many assets that help developers to learn a new API.
Developer portal or documentation site UI design. Usability and graphics are both important.
Use company branding and content creation guidelines. But remember, your audience is much more technical than the average customer.
Can all your API consumers access all APIs?
Depending on developer portal capabilities and API -specific configuration developers can subscribe access to APIs with
- self-service or
- self-service with approval workflow
Content and communication guidelines
All human readable API documentation pages should be created automatically from API productization and OpenAPI documents. Masters should be stored and edited using version control, not just in the developer portal / documentation site.
Content, language, what information is shared, which channels and formats are used, etc. should be planned and optimized for your developer community.
Terms and conditions for using our APIs are important. Remember to create them together with business, legal and technology people. They need to address privacy and re-use, service levels and data ownership. Try to still keep them understandable.
You can create SDKs or provide code snippets. Remember that not all developers undestand cURL and that maintaining SDK will require work. Your Developer Portal may provide you a way to generate code snippets automatically from an Open API definition.
Presentations and demos help developers understand what they can use the API for. They may also need help in using the tools or figuring out the authentication. so make sure you address that, too.
Think how you are going to collect feedback and feature suggestions.
Some additional things that can impact developer experience:
- Marketing communication (ads, swag, press releases…)
- Monetization (API pricing and payments handling) can be used, if your API business model requires it and your own or your API management platform supports it natively or by connecting to payment gateways.
- Customer stories (testimonials, interviews etc.)
- Release notes/change logs
- Plugins and ready-made integrations
Choose your identities carefully
Pay a few moments of attention to how your API Consuming applications and developers need to authenticate to your APIs and your developer portal. Your priority maybe to make it very easy, but remember to make it secure enough.
method for lean api development
Great APIs need skilled people and a good method, which let's you create APIs as products - fast.
APIOps Cycles method is vendor & technology-neutral.
Read the free e-book "The 8 wastes of lean in API development". Learn quick tips on how to remove the wastes using the APIOps Cycles method.
