A picture is worth a thousand words…
That is one of the reasons why we like to represent the most complex ideas of software through pictures and diagrams. Class and sequence diagrams are most commonly understood but there are a large number of diagrammatic representations of various software and architectural concepts that have grown over time. A diagram generally provides an easy to digest overview of complex software architecture. In my experience, this forms a foundation of understanding that greatly helps while getting to understand that architecture in detail. Like most people, I really like this approach. One area where I have struggled to do this and is forced to go straight into low-level details is API documentation. When we want to consume a new API, we are usually given an API spec. Most likely this spec is written in Swagger which does a good job is describing low-level details of what each endpoint in the API does. This works quite well for very simple APIs. But the moment the complexity of APIs grows, I crave for that basic understanding of the API that makes diving into the details a bearable process.
Recently, I tried to address this by putting out an overview diagram for the APIs that my team delivered. I call this API Map. I took inspiration from class diagram as it nicely answers the questions that I usually have when I see API specs that are beyond simple.
1. What are all the resources that this API exposes?
2. How are the resources related to each other?
3. How do I perform important operations on key resources?
As you may have guessed, the API map centres around resource, a core tenet of REST. Diagrammatic representation I used for a resource is very close to a class with a few obvious differences.
It has got a resource name and resource description. This can be copied from your API specs for the sake of consistency. Then it lists all the endpoints around that resource grouped by four main HTTP verbs we use in REST APIs — GET, POST, PUT and DELETE. This is not prescriptive. If a resource does not have any DELETE endpoint then I would not have a DELETE section on my diagram. Similarly, if you use other HTTP verbs then feel free to add them. Next, to the verb, we mention endpoint URLs that correspond to that verb. This is a free text field with no prescribed way of how we provide this information. We can be as creative as we want here.
Let’s use an example API for a library. That’s simple enough for a blog post. In a simple library API, you would have books, authors, members and their rentals. A book resource in an API map can look like the below.
Representation of book resource in API Map
This is a very standard CRUD API. There is more than one way to get a book which is all listed. An interesting one is to get all the books written by an author. We will visit this endpoint again in the next section about relations. This endpoint is captured under book resource as the endpoint returns a list of books.
Let’s look at relations next. There is a bi-directional relation between a book and an author. A book has one or more authors. An author has one or more books. Let’s say, we have decided not to support the bi-directional relation in our APIs. We only support “the author has one or more books” relation. This relation is embodied into the endpoint /author/{id}/books which returns all the books written by the author having specified id. This is listed under book resource as it returns a list of books. However, without a visual aid, finding out such relations by scanning all the endpoints on a relatively bigger API map is challenging. So we use lines with arrows and text to represent such relation.
The relation between two resources represented visually in an API Map
Instead of drawing a random line from one resource to another, we draw them as close to the endpoint in question as possible. This makes it easy to find out which endpoint represents that relationship.
The author endpoint could be modelled entirely differently. For example, you may never expose an endpoint to add authors explicitly because they are automatically when a book is added. Same applies to deleting authors.
That’s it really. This is how a complete API map for our simple library API looks like.
Sometimes there is indirect relation between two resources. In our example, members have an indirect relation to books when they rent books. This relation is via a rental resource. If it is worth highlighting the indirect relation then we use a dotted line to represent it with all other conventions being the same.
Is this not just an ER diagram for APIs?
I will not blame you if you felt that this is just an ER diagram for APIs. The simple library example with mostly CRUD-like API Methods is partly to blame. However, if your API is designed to be CRUD-like then your API Map will look similar to an ER diagram. This is still a good thing because the API Map is bringing to the surface the fact that the API is designed like that, intentionally or unintentionally. But back to the original question — is API Map really just an ER diagram for the API? Think of the following
- An ER diagram describes the structure of the tables. API Map does not focus on the structure of the resources.
- The only relation between entities that an ER diagram describes is that of cardinality. In an API Map, in addition to cardinality, you can use rich relation descriptor as it’s just a free text.
- In a traditional sense, an ER diagram is a design tool. You would design your databases using an ER diagram and then build the actual DDL scripts from it unless you auto-generated your DDL using an ORM. API Map is not a design tool. It merely describes an API after it is implemented.
- An ER diagram documents the structure of entities and relations between them but does not talk about how you can interact with those entities e.g. via stored procedures, functions and triggers. API Map, on the other hand, emphasises on API methods through which consumers interact with the resources. As an API consumer if you cannot access or modify a resource via one of the described API methods then you cannot access or modify that resource.
API diagram has some similarities to ER diagram but its intention is very different from that of an ER diagram. Having said that, It would be useful to take some inspiration from an ER diagram to enhance API Map. We can use standard cardinality notations from ER diagram if that helps. If you believe it will help to include important attributes on the resources in an API Map, the way ER diagram does, feel free to do that too. I don’t think it's about whether API Map is just an ER diagram or not. It’s about what value does API Map add and in my opinion, it does add value.
In closing
This still has some gaps, however, it has tremendously helped me introduce complex APIs to new developers in a gentler way. I usually show new developers an API map before I throw them into complex swagger specs. The only challenge I have faced so far is that drawing this diagram up can be time-consuming if you try to use standard diagramming tools. You would need to resize and move shapes around in order to fit all the text and stack the shapes next to each other nicely. Visio does a great job at this and is my tool of choice. A hand drawing should also do a good judgement of this diagram.
What do you use to visually represent your APIs? Let me know via comments.
☞ If you like my article, please don’t forget to click ❤ to recommend it to others.
Also, to be notified about my new articles and stories, follow me on Medium and Twitter. You can find me on LinkedIn as well. Cheers!