API Modeling

This is a continued blog post series you can find the first post here. Resumé of chapter 1

You can use an eraser on the drafting table or a sledgehammer on the construction site.

— Frank Lloyd Wright

Chapter 6 starts explaining why rushing to code often ends being more expensive than spending time designing the API with other means than code. The quote  above should give a hint in that direction.

Rather in the design phase we should only use code as smaller experiments to gain knowledge, to get a “hole through” like its explained with the often cited “tracer bullet” analogy.

API Model vs. API Design

API Modeling is introduced as the thing that prepares you to do the next step in the process which is API Design.

The tangible artefact of API Modelling is a so called API Profile. 

An API Profile contains all the needed knowledge about the API, but is still agnostic towards specific implementation styles like REST, gRPC or GraphQL.

Also an API profile is different from a specification like the Open API Specification (OAS). The chapter points to another standard format better suited than OAS to represent an API Profile, which is the “Application-Level Profile Semantics” (ALPS) format. Chapter 13 Goes into details about that.

API Profile Structure

An API profile captures the following details about each API:

  • The name and a short description of the API
  • The scope of the API (internal, public, partner, etc.)
  • API operations with input and output message details
  • Participants allowed to perform each operation, in preparation for securing the API
  • Events generated by each API operation, to drive extensibility beyond the API’s original intent
  • (Optional) architectural requirements identified, such as a service-level agreement (SLA)
 
book store api profile example
API Profile example for the book store shopping API

Above example can be found at LaunchAny’s Github Repo

API Profile design process

We get introduced to yet  another nested process for designing the API profile. Who said this would be easy. But what we get is actually a helping hand from an experienced API Designer. So here are the steps.

Step 1: Capture API Profile Summary

This simply includes filling out the 3 first bullets of the API profile structure. Use Activities and Activity steps from previous chapters to fill out the operation name column.

Step 2: Identify the Resources

This will fill the Resource(s) column of the API Profile

Resources are often entities or aggregate root’s. Use previous design artefacts to help here. The Event Storming Canvas will reveal resource candidates.

For each resource define a new table (spread sheet) that catches the resource properties including property name and description.

a cart api resource example
API resource example from the book.

more examples of resources

It noted that an outside-in approach is recommended when designing API resources. Don’t go from Database schema to API Resources. The danger is that you will end up leaking technical details not suited for an API.

Step 3: Define the Resource Taxonomy

Resource Taxonomy can be understood as the relationship between resources. This step is not represented int the  API Profile spread sheet. But You should make a diagram of the resources and all their relationships.

This exercise is important. Relationships are categorized into 3 different types:

  • Dependent
  • Independent 
  • Associative

Associative means that the resources my exist independently but additional properties needs to describe the relation ship if it exists. In the shopping API we encounter the cartItem as a new resource needed to describe the relationship between a cart and a book.

So this step is crucial for capturing needed details that would other vise be missing in later steps. Below we see properties like quantity and unit price on a new resource that we hadn’t previously covered in the design.

cart item api resource table

Step 4: Add Operation Events

This corresponds to filling out the ‘Emitted Events’ column in the API Profile spreadsheet. Again the event storming exercise from previous chapters can be used here. 

Step 5: Expand Operation Details

Capture details about the operation, but don’t be overly concerned to get everything included. The important thing is to provide alignment and common understanding. Later steps will capture all details. 

Instead be sure to capture the following safety classifications.

There are three classifications of safety for HTTP operations:

  • Safe: The operation does not make any state changes to the target resource(s). This safety classification is assigned to all read-based (GET) operations.
  • Idempotent: The operation makes state changes to the target resource(s), but if the operation is executed with the same input, it will produce the same result. This is important, as it informs API clients if they can reissue a request that previously failed, without additional side effects. This safety classification is assigned to replace and delete operations (PUT and DELETE).
  • Unsafe: The operation makes state changes to the target resource(s) and cannot guarantee the same results if called multiple times with the same input. This safety classification is typically assigned to create and update (POST and PATCH) operations.

Validating the API Model with Sequence Diagrams

By now that API profile should be complete, but James suggests to validate the API profile by creating sequence diagrams. This will visualize the conversation going on between API user and the API. The API Profile must support a coherent Sequence Diagram.

 

shopping sequence diagram

Evaluating API Priority and Reuse

Finally do another validation exercise. By asking yourself the following questions:

  • Does the API help provide a competitive advantage over other market offerings?

  • Does the API reduce the cost of doing business, perhaps by reducing manual processes?

  • Does the API create a new revenue stream or improve an existing revenue stream?

  • Is the API producing business intelligence, market insights, or decisioning factors?

  • Does the API automate repetitive tasks that free the organization for more critical business functions?

The chapter gives even more recommendations on how to evaluate the feasibility of building an API.  I will not replicate everything here.

Summary

I have the following comments to the chapter

This book tries to hammer the importance of outcome in to the mind of the reader. And I support that. I have previously referenced Jeff Patton’s Book “User Story Mapping”

In that book he also brings forth the Tracer Bullet analogy, when he explains the advantage of creating a so called backbone of activities that represents steps the user must perform to achieve an out come. The user story map gives exactly that overview. I Think the ADDR process systematically  leads to artifacts that leads to the same kind of overview.

We shouldn’t try to make production ready code to soon, since we inevitably will need corrections, and a process like the ADDR is more effective since its easier to correct mistakes at this level.

The chapter suggests a clear process for advancing the API Design. We are still more on the product, user , business level than on the technical level.

One can imagine how this could get an organizations up to speed, when they first get the hang of following this process.

Things that might look daunting or complex gets broken down to smaller consumable chunks in a format suitable for all stakeholders to understand. This fosters better collaboration than a developer team rushing to code.

Why do we so often see teams and organization’s skipping all of this?

I think two things among other springs to mind: 

  • The misconception that the only work developers should do is to code. If a developer can type in code 100% of their time then its considered optimal use of that resource (employee ). This stems from an outdated mindset that we do simple repetitive work. The fact is that software development is  highly cognitive and creative and as such requires a lot of thinking. Thinking gets catalyzed by collaboration and visualization. Read more about this in Dave Marquet’s Leadership is Language
  • In a lot of organizations people are feed up with meetings. They feel they participate in a lot of fruitless meetings. So its natural to long for just being able to say  “we are coding”,  since its feels and sounds more productive. A process like ADDR is highly collaborative. Collaboration might require planning meetings. Which just gets seen as more waste of time. I Think the solution is to demonstrate that meetings can be effective and lead to visible results in the shape of tangible artifacts.  This book is a recipe for facilitating this.