Touchpoints of a REST API

When developing a REST API we often think of it as an HTTP web service running on some web servers. But that is only the tip of the iceberg; professional API developers know that a successful REST API is an ecosystem that consists of many moving parts that need to fit together. In this blog post, I will try to present the main users of a REST API as well as their flow of interactions with the different touchpoints that make up an API ecosystem.

Read on… it will all make sense at the end…

Who uses an API?

So,  who is actually using a REST API?
To answer that question let’s look at some of the typical users of a REST API:

• The App Developer (web/mobile apps)
• The Backend Developer
• The DevOps engineer
• The IT Manager
• The API Designer
• The API Developer

Common for all API-users is that they are all IT- or software-focused. This is, in contrast, to e.g. a website where a user can potentially be any person on the planet with an internet-capable device.

The API touchpoints and ecosystem

The API users interact with your API in different ways using different touchpoints.
The API users, the API touchpoints and the associated interactions between users and touchpoints is what I define as the API Ecosystem.

So let’s look at the touchpoints that typically exists for a REST API:

• REST API Service
  • This is the actual REST API running on some servers somewhere
• Documentation
  • API documentation containing usage guidelines, a reference to API operations and resources etc…
  • Also knows as API Reference
• Contract (often Swagger/OpenAPI Spec)
  • The contract specifying the API interface. The two most popular contract formats are Swagger 2.0 and OpenAPI Spec 3.0. Not all REST APIs use contracts.
  • NOTE: For good ol’ SOAP APIs the contract format is WSDL
• Client App
  • A web app or mobile app that uses the API
• Client Service
  • Another (backend) service that uses the API (service-to-service calls)
• Changelogs/revisions
  • A list of changelogs and revision changes.
• Issues
  • Issues reported to the API developers
• SLA (Service Level Agreement)
  • A document describing the operational obligations of a running API
• Metrics
  • Metrics and statistics around response time, usage statistics, throttling, etc. for the API

The different API users will interact very differently with the API touchpoints and it is therefore important to analyze the usage patterns of your most important users in order to provide a professional API experience. We will use the “TouchPoint Matrix” for this purpose.

The Touchpoints Matrix for a REST API

The figure below depicts a Touchpoints Matrix: a matrix of touchpoints and activities. The rows in the matrix represent the touchpoints described in the previous section (e.g. ‘REST Service’, ‘Documentation’, ‘Contract’). The columns in the matrix represent activities that a user carries out when interacting with a touchpoint. Not all activities apply to all touchpoints therefore only combinations marked with ‘X’ makes a fit (e.g. a user can ‘Query’ a ‘RESP API Service’ and ‘View’ the ‘Documentation’).

So, let’s look at how to apply the touchpoints matrix for the ‘App Developer‘ user.

Touchpoints Matrix for the ‘App Developer‘

The figure shows the ‘App Developers‘ flow of interactions with the API ecosystem. Basically, it tells us that the App Developer (re)views the documentation and API contract. He then does some (experimental) queries on the REST API service and the docs. The developer then produces a client app and does some queries/experiments/tests on the new app. Finally, the developer reports issues (if any) to the API developers.

Now, let’s look at another example where the ‘DevOps Engineer‘ uses the API in a very different way.

Touchpoints Matrix for the ‘DevOps Engineer‘

The DevOps Engineer has a very different flow of interaction as shown in the figure below. In this figure, green clouds are used to divide the flow of interactions into groups. Each group is described with a yellow post-it note.

Where to go from here?

You can probably imagine that the flow of interactions for the ‘API Designer’ will look very different from the two previous matrices, and the flow for the ‘API Manager‘ will look even more different. This states the main point of this blog post: the users of your REST API interacts very differently with your API ecosystem. Your API design should reflect the needs of all your users.

I usually encourage people to use an API management service like Azure API Management or one of the competitors. With an API Management solution, you have your main touchpoints and interactions covered in a single system and you can concentrate on making your awesome API.

I hope this blog post has enriched your view on REST APIs and API Ecosystems and I hope that the touchpoint matrices can enrich your API design discussions. I also hope you will share your thoughts and opinions in the comments below; I encourage you to sign up for my newsletter and follow me on Twitter.