Jan Vlnas - Why your API doesn’t solve my problem: A use case-driven API design

Jan Vlnas

Developer Advocate at Superface

Jan's presentation

Jan's slides

Q&A

• Where do you, as the developer advocate, come in?
• What you call a use case tutorial, would that be what we could also call a worked example?
• Because you are called to the problematic spaces, where is that invisible wall that is so hard to cross?
• How much Behavioral Driven Development makes sense in API development while being use-case driven? Are these two, Behavioral Driven Development and Use-case Driven development, the same?
• How would you differentiate between guides and tutorials?
• Do you also give advice on what to translate, what not to translate? Which parts of this whole documentation do you start translating?

Introduction

The most expensive part of API integrations isn’t coding or figuring out how to connect the SDK, it’s the analysis: understanding how the API works and how to use it. In this presentation, Jan talks about APIs from the developers’ perspective, how developers perceive the API, and what API providers can do to help them.

Why should the developer use the API?

To solve their problem. Developers will use the API to fulfill a use case for their application. A use case is a scenario where the API is useful to implement some part or feature in the developer’s application.

Use case #1

The developer is building a registration system (including login, sign up, and password reset). They need to send a password reset email with a link for the user, so they need to look up some email API providers.

• Jan might find a provider which is simply an email service; there’s nothing about password resets.
• On a different provider’s Solutions page, the service includes sending transactional emails, including password reset emails.

As a developer, Jan is trying to match his use case with some features of the API, its capabilities, and what the API can offer.

Users don’t speak the API provider’s language

• The hard part about understanding APIs: developers think about their use case in their language while API providers present the API capabilities in their terminology.
• The developer is not an expert in the API provider’s domain which is why they need to use the API in the first place.
• Developers need to map their use case to the API’s capabilities, translate the terminology and data structures and understand all the flows and processes. This is what takes the most time when developers deal with an API where they don’t understand the problem domain.

Use case #2

The developer wants to know how their open source project is doing, they want to know who gives a star to their project. Although the metric of popularity on both is stars, the two have different concepts (GitHub has “repositories” and “stargazers”; GitLab has “projects” and “starrers”). They also both offer REST and GraphQL APIs, so the developer has to decide which one to use to translate their use case to API calls.

Developers have to do a lot of mapping when integrating an API.

The developer needs to understand

• The problem domain of the API, the terminology, the processes and flows;
• The business rules of the API (pricing structure, rate limits, authentication scopes, etc.) to know what happens as their usage increases, and what’s the impact on the long-term maintenance of the integration;
• What the API offers in terms of features and capabilities which are relevant to them;
• The developer needs to translate their use case to the capabilities of the API.

How can API providers make integration easier for developers?

• Treat APIs as a product and have a dedicated product owner. Many companies treat their APIs as a secondary feature with no oversight or no quality control.
• Product owners understand the users and their needs, they understand the developer’s problem domain, the context in which they will use the API.

The API product owner should

• Understand and discover use cases relying on user research. What is the developer building? Do they prefer REST or GraphQL?
• Research competitors: can the API product owner improve on their use cases? They should not blindly copy the documentation and the APIs but improve it.
• Look at the code to see how the API is used in the wild. GitHub repositories can be organized into topics by their authors, which can be helpful for better understanding of the domain of the API provider’s users, the domain where the API is used.
• If this is relevant to the API provider’s domain, look at how multi-provider SDKs are used and whether it’s something the API provider can acknowledge and recommend to their users.
• Check dependency graphs on projects and awesome lists on various topics like platforms, programming languages, and particular problem domains.

Present different use cases

• Provide solutions, e.g. on the Solutions page of the API provider’s website.
• Provide use case guides. These should cover common scenarios where the API is used. These use case guides may explain common flows or point the developer to parts of the API relevant for their use case.
• Provide use case tutorials. Use case tutorials can be very useful for new developers. However, very often the documentation covers product tutorials focused on particular features of the API or product. What developers need are use case tutorials on how to adjust the code to their use case.

Use case-driven API design

• Start with user research and use cases discovery for the API;
• Technological decisions should come after that: what sort of API makes sense for these use cases (REST API, GraphQL, etc.);
• The choice of technology informs the design of the API;
• The specification comes next (e.g., an openAPI document) which will help the API provider test the implementation, and use it to build and test guides and tutorials even without building the API (a well-written specification allows mocking the API and testing those guides and tutorials with the API provider’s users).

So, why doesn’t the API solve the developer’s problem?

Because they can’t understand it.

Typically, the API documentation includes references of end points, data models, product tutorials or even an API specification. These are all great to understand the capabilities of the API, they can serve as a map, they give the developer an idea where they can go with the API but it’s up to them to find their way around.

Solutions and guides, explaining use cases can act as a sort of turn-by-turn navigation. If the API provider also gives the developer a use case tutorial, that would be like giving them a vehicle to get faster towards their goal.