From data aggregators at the core of open banking to payment processors for digital marketplaces – many FinTech products deliver value through application programming interfaces (aka APIs). In those cases, it’s hard to speak of User Experience as such. What becomes important then is Developer Experience (DX), which reflects how easy it is to work and integrate with an API. This in turn, can have a huge impact on the final quality and scalability of the API product. So if your goal is to build a highly-performant, future-proof and integration-ready solution, don’t forget about Developer Experience. Use the pro tips below to accelerate and empower your API development process.
Developers in the API economy
A standard API lifecycle often takes the form of an infinity loop, with two main agents putting things in motion:
- API providers, responsible for planning, building, documenting, testing, deployment and management.
- API consumers, who discover, implement, optimise, monitor, and maintain integration.
Decisions made by the providers have direct consequences for the consumers, especially in terms of discovery and implementation. On the other hand, the consumers’ feedback is what fuels versioning and enables future improvements.
Developers play a crucial role in the API economy, because they are both creators and technical adopters of software products. Their influence stretches from each line of code to buying decisions about the solutions that organizations plan to implement. In this context, good Developer Experience is not only a measure of technological efficiency. It can also determine the commercial value and marketability of API products, especially if you opt for API-first approach.
Developer Experience in API development: tips & tools
Although each development project is unique in terms of scale and complexity, a set of good practices can help you build an optimal Developer Experience and tailor it to your specific needs. When paired with the right toolset, a DX strategy can not only elevate the final product but also speed up development and facilitate change management.
API is only as good as its documentation…
What might strike you as a bold statement is actually a common belief among seasoned engineers. This combination of technical writing, code samples and use cases is the first point of contact and a regular point of reference for all users/consumers of your API. So if they struggle to understand the purpose and main functions of the product, you might be in real trouble. Even the most revolutionary idea can be nipped in the bud if it’s not successfully communicated to the target audience.
Let’s start with just one page where developers can find all the essential information about your API. Even if you have several pages with various development-related resources, try to chain them with global navigation. Plan the directory strategically and make sure to cover all fundamentals:
- authentication
- errors
- end points
- terms of use
- changelog
- request-response cycle
Developers should be able to quickly learn what to expect from a successful call and get an idea of sample responses and supported formats. For exceptional DX, consider including HTTP response status codes and error descriptions.
Language & terminology
Finding the right language to introduce users to your API is equally important. Make sure the documentation is accurate, up-to-date, clear, and concise. On that note, it’s risky to assume your audience is 100% developers. Make room for other decision makers:
- Project Managers, wondering whether the API can solve a given problem.
- Lead Engineers and CTOs, evaluating the API in the context of their business needs.
Not all users are fully familiar with domain jargon, so try to provide enough context for API-specific terminology.
OpenAPI/Swagger
Speaking of documentation, manually updated PDFs or static web pages are definitely a thing of the past. Modern API frameworks such as Swagger and OpenAPI Specification (OAS), used for designing and building APIs, include features enabling automated documentation flow. With OAS, developers get a common description format, building blocks for generating and customising interactive API docs, as well as other handy features, such as adding sample requests and responses. OpenAPI/Swagger is considered standard in documenting REST APIs. Most developers are familiar with it and will expect it within the developer documentation.
The power of experimentation
Another good practice is to provide a sandbox environment, where developers can quickly check how the API is working. If you fill it with a set of test data, they don’t have to waste time on setup and can start experimenting straight away. Going a step further, you can also use cURL to include sample requests, which can be copied and immediately tested for responses.
Step-by-step instructions, showing how the API could be used in a valid sequence, can significantly speed up integration. Tutorials and guides are mighty knowledge-sharing tools and should be an integral part of API documentation. By the rule of thumb, it’s best when they’re both comprehensive and focused. From the developer’s perspective, general flows and data models might be more vital than the exact details of each end point.
Need a REST? Postman to the rescue!
In RESTful APIs, Developer Experience can be poor if the API is not quite as REST as it should be… And it’s more often the case than you’d expect. For more guidance, you can use the Richardson Maturity Model, which describes different levels of an API being REST. Make sure that you are at least at Level 2 called HTTP Verbs.
Postman is a comprehensive tool that helps developers and QA engineers work with REST APIs, particularly useful in the case of more complex systems. A ready-to-use Postman collection is something that most developers will definitely appreciate, as it helps them save a lot of time and effort.
Integration boost
Integrating with an API shouldn’t feel like climbing the walls. You can make the developers’ lives a lot easier by providing auto-generated Software Development Kits (SDKs) for common programming languages or platforms. For JavaScript and TypeScript projects, you can use Node Package Manager and publish SDKs as public npm packages, so your client’s developers can test your API in their CI/CD pipelines. It makes the whole integration process much more robust and easy to maintain. Similar solutions are also available for other languages, e.g. NuGet package manager dedicated to .NET development.
Developer Experience matters!
The API economy offers FinTech businesses countless options of connecting their products to boost them with financial data or processing power. However, the growing complexity of the digital landscape calls for shedding more light on Developer Experience in API development. Forget about developers and your API is in risk of never fulfilling its potential or worse: sinking into oblivion. Recognize and empower them instead – and the chances for world-wide adoption of your API-enabled solution might just skyrocket.