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…
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:
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 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.
There exist several definitions of what an API Ecosystem is; some tied more closely to API Economy. Share in the comments your view of an API Ecosystem definition.
So let’s look at the touchpoints that typically exists for a REST 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 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.
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.
The steps of interaction don’t necessarily happen in the depicted order, so feel free to change it to fit your use-cases.
Now, let’s look at another example where the ‘DevOps Engineer‘ uses the API in a very different way.
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.
Some people might rightfully argue that there should also be an activity-column called ‘Operate‘. This activity should then cover the operational activities associated with running the REST API Service and/or its consumers. In practice, pure ‘operation’ of an API is often more associated with the infrastructure on which the REST API runs and hence not directly related to the API Ecosystem itself – so that’s why I haven’t included it in my matrix. I would love to hear your comments about this, though.
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.7
Open API Specification 3 support in Azure API Management is now GA (generally available)
Azure API Management: Authorization Level Based Content in the Developer Portal
Azure API Management: Hiding Developer Portal from anonymous users [step-by-step guide]