This is a story inspired by true events, about a team and the everyday struggles they faced while building an API defined by spreadsheets and documents. What can come to the rescue in such a scenario? API specifications.

In analysis

Here’s an example of a conversation that you may have been part of sometime in your life as a developer.

Business Analyst: Our next user story involves creating an API (let’s call it “Customer API”).
Developer A: How novel! That’s what I did yesterday and the day before and the day before that.
Business Analyst: Great, should I let the clients know that it wouldn’t take as long to build it?
Developer A: Hold on. We haven’t even heard the requirements for Customer API.
Business Analyst: It’s just a couple of hundred fields that Customer API needs to send to another downstream API to perform the transaction.
Developer A: And how will we know the values for these fields that Customer API needs to send?
Business Analyst: I’ll take care of it. I have already spoken to the lead developer from the downstream API team, and he’s sent me a spreadsheet. It has all the fields and the values that need to be part of the request body. He’s also sent me a document with information on the headers and auth details required to call the downstream API.
Developer A: Is this downstream API available in a testing environment? A playground, maybe?
Business Analyst: They’re still working on building the downstream API, so they don’t have a working version yet.

In development

Developer A gets to work. She pairs with Developer B, another application developer on her team, to finish the Customer API story. Business Analyst sends them an email with a spreadsheet containing the fields and a document that includes the API currently in development by the downstream API team. It seems like Developer A and Developer B have all the information required to start building the Customer API, so they come up with the following list of tasks:

1. Create the Customer Request model that has all the fields from the spreadsheet.
2. Fill the model with default values.
3. Build the Customer API that will use this model as part of the request body.

Seems straightforward. That’s what Developer A and Developer B felt too. Let's see what happened.

In the soup

When Developer A and Developer B scanned the spreadsheet, it didn’t have a hundred fields (as Business Analyst said) but 300 fields. Did that slow them down? Yes, it did.

Let’s look at some of the challenges they faced and what they did.

How did Developer A and Developer B convert fields from the spreadsheet to data members of a class?

Developer B started by showing off some editing skills in his favorite integrated development environment (IDE). To be fair, he recently acquired these skills from another developer last week. Now was his chance to shine. He simply showed Developer A how to paste the fields from the spreadsheet to the class file and some shortcuts on the IDE to clean the copy/paste bit and replace it with Kotlin (the language they used) syntax for a class.

How did they assign the values to the fields?

Not all fields had default values, so assigning defaults to specific fields became a manual process for them, which of course took a while and some patience to complete.

Why are we saying they were in the soup?

Because here’s what happened over the course of the project. Integration failed due to:

• Incorrectly spelled fields
• Case sensitive fields
• Mismatched data types: Some fields were represented as Boolean when they were actually Strings
• Error parsing issues, since the document misrepresented it
• Missing responses (200 OK even) for some paths

In retrospect

I relate to the character of Developer A in this scenario so much, because these are issues that my team has faced. For us, the problems kept popping up frequently, and the integration took a couple of months. I always wondered if there was a better way to communicate—or a process to spend less time on—the issues we faced. Fast-forward to today, and I am glad to report that I’m now fairly acquainted with API specifications.

What are API specifications, and why use them?

A spreadsheet (or a doc) may be tempting to use because it doesn’t come with a lot of rules, but a specification has the same benefit plus more. Here are a few reasons why I’ve become an advocate of specifications (like the OpenAPI Specification):

Conformance to a format

Specifications have a format, and the format could be JSON/YAML, which is much closer to an API than plain text. Examples of APIs and their formats:

• Twilio Messaging API: Defined in JSON format
• Postman API: Defined in YAML format

Schema objects

Schema objects can be defined, and that would resolve the error response parsing issues we faced earlier. Below is an example of a defined schema object.

In the Dolby Media Analyze OpenAPI, RequestError is a schema object defined as follows:

RequestError:     
     type: object     
     properties:       
       type:         
         description: A URL that uniquely identifies the problem type.         
         type: string         
         example: "/problem/validation-error"       
     title:         
       description: A human readable description of the error.         
       type: string         
       example: "Your request parameters didn't validate"       
     status:         
       description: The HTTP response code.         
       type: number         
       example: 400       
     instance:         
       description: The URL of the call for which the error occurred.         
       type: string         
       example: "/media/analyze"       
     detail:         
       description: An optional field with more information depending on the type.         
       type: string         
       example: "job_id is required"

Schema validations

Validations on the specification ensure that at least one successful response is defined for a path. In addition, there are a lot of other validations on the schema.

The above screenshot displays validation errors found in the schema. Dive right into the Discourse API (Validation Errors Example) to learn more.

Tooling

Specifications are supported by extensive tooling—like code generators, mock servers, documentation, etc. Leverage the tooling available in Postman by following the detailed walkthrough here.

Helpful API blueprints

API specifications are a blueprint for APIs, providing a huge help by describing the structure of the API. Read Postman Chief Evangelist Kin Lane’s blog post to get a high-level view of API specifications currently available.

Spreadsheets served us well in the information age, but as enterprise organizations wrestle with their digital transformation, they are realizing they need a much more precise set of human- and machine-readable tools that can track the exponentially increasing data being produced each day. Specifications now help teams keep up with the perpetual pace of change and remain competitive in today’s ever-evolving and shifting digital landscape.
— Postman Chief Evangelist Kin Lane

To get started, you can define the API schema in Postman using the API Builder. Share your experiences with and without specifications, and then give us your feedback by leaving a comment below.