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.
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.
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:
- Create the Customer Request model that has all the fields from the spreadsheet.
- Fill the model with default values.
- 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
A developer can feel in the soup due to integration failure
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 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”
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.
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.
Postman provides a wide range of functions and features to assist with API development, testing, and collaboration. Here are some commonly used functions in Postman:
Creating and Managing Requests: Postman allows you to create API requests by specifying the request method, URL, headers, parameters, and body. You can manage and organize requests within collections, including creating folders, adding descriptions, and reordering requests.
Request and Response Visualization: Postman provides a user-friendly interface to view and analyze request and response data. It supports syntax highlighting for various data formats such as JSON, XML, and HTML, making it easier to understand and validate the data.
Environment and Variables: Postman allows you to define variables and environments. Variables enable you to store and reuse dynamic values across requests, making them flexible and easy to maintain. Environments provide sets of variables specific to different environments (e.g., development, staging, production).
Pre-request Scripts: Postman enables you to execute scripts before sending API requests using pre-request scripts. These scripts can be used to dynamically generate values, manipulate data, or set variables based on specific conditions.
Collection Runner: The Collection Runner allows you to execute a series of requests in a collection. It enables you to perform data-driven testing by iterating over multiple sets of data or environments. You can configure iterations, delays, and data sources for more comprehensive testing.
Mock Servers: Postman allows you to create mock servers for simulating API responses without a live backend. Mock servers are useful during development, allowing frontend developers to work independently by providing simulated API responses.
Documentation Generation: Postman can automatically generate documentation for your APIs based on your requests and collections. It provides a simple way to share API specifications and details with stakeholders.
Collaboration and Teamwork: Postman offers collaboration features such as sharing collections, collaborating on requests, and commenting on specific requests or collections. It also supports version control integration to manage changes and updates effectively.
Integration and Automation: Postman integrates with various tools and services, including version control systems (e.g., Git), CI/CD platforms (e.g., Jenkins), and API management solutions. It provides options for integrating with these tools to automate API testing and deployment processes.