Problem: Spreadsheets. Solution: Specifications

Meenakshi Dhanani
Apr 22 · 6 min read
Photo by ThisisEngineering RAEng on Unsplash

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? API specifications.

In analysis

A business analyst and a developer may have different objectives and perspectives

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:

Seems straightforward. That’s what Developer A and Developer B felt too.

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:

A developer can feel in the soup due to integration failure

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:

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.

Discourse API (Validation Errors Example) demonstrating validation errors

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.

Originally published at https://blog.postman.com on April 22, 2021.

Better Practices

For individual engineers to the largest teams, Better…

Better Practices

For individual engineers to the largest teams, Better Practices is intended to distill knowledge from the Postman community. This is a place to learn about modern software practices together! Read more: https://medium.com/better-practices/introducing-better-practices-e9cf14cf0c88

Meenakshi Dhanani

Written by

Developer Advocate @Postman

Better Practices

For individual engineers to the largest teams, Better Practices is intended to distill knowledge from the Postman community. This is a place to learn about modern software practices together! Read more: https://medium.com/better-practices/introducing-better-practices-e9cf14cf0c88

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store