APIs are the building blocks of modern software. Having a contract in place to build an API facilitates easier communication between the parties involved. But what happens when the format of the contract tends to increase arguments among team members? That’s where open source specifications that define APIs come in, and spreadsheets don’t help.
Open source, in simple terms, is defined as software where the copyright holder grants users the right to use, modify, and distribute the software and its source code to anyone, for any purpose. Despite open source specifications being one of the most critical components of the ecosystem, these are not talked of often. As a matter of fact, the specifications of software are what make it distinctive. These specifications are also discussed, debated on and argued about in development teams, but not much is written about them. Is there a way for teams to stop arguing about, and start cashing in on open source specifications?
Let’s answer that question with a story!
The loan app specifications
This story revolves around a team developing an app intended to help bank customers sign up for securing a loan at the click of a button. Sonali, a business analyst in the team, walks up and informs her colleagues that they need to build a feature that allows customers to apply for a loan, using a downstream customer application programming interface (API) exposed by the client. She asks the team about the time required to develop this feature.
Meera, who is an application developer in the team, comes in. She is really smart and does not commit any timeline for delivering the feature. Instead, she asks and seeks more clarity on the downstream API that will be used. She also asks if there is a sandbox environment to test the API.
Sonali tells Meera that she will loop in the team on the email received from the client. She also explains to Meera about how that email contains documents and spreadsheets relevant to the feature.
Now, as the feature requires a lot of fields (354 to be precise), Meera picks up all the 354 feeds from the sheets, uses her editing skills, and posts the status of the task as ‘dev done’. Sonali, after a few days, comes back to meet Meera and informs her that the client has requested for some clarifications about the feature, and the contract. The client, Sonali informs, has also requested for minor changes. Meera leaves the project she is working on, and goes back to the bank loan feature to add and make changes as suggested by the client, but because the changes are minor, she is not quite excited about making them.
Fast forward a few months later, and the story is still not over! The testers who are checking the API realise that there are a lot more things that need to be done. They also notice the error responses that are coming from the API are different from the ones mentioned in the contract. Even the 200 ‘OK’ responses are different, probably because of the way they are defined in the document.
This is the point where Meera gets a little irritated as the work is not interesting. She is also tired of the time the feature is taking, in addition to the blame game taking place inside the team. Hence, at this point, the arguments begin.
A lot of changes later, the team manages to push the feature ahead and, as it gets delivered, the team members start looking at charting a map to zone what did and did not go well.
| A few open source specifications that can be used to define your APIs are described briefly below.
OpenAPI Specification (OAS): This specification is useful for defining REST APIs. It is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation collaborative project. This specification defines a standard, programming language-independent interface description for HTTP APIs that allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code. AsyncAPI: AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA). The long-term goal of the project is to make working with EDAs as easy as it is to work with REST APIs. The AsyncAPI specification settles the base for a greater and better tooling ecosystem for EDAs. You may use this specification if you are looking for a solution to automate and formalise the documentation or code generation of your event-driven (micro)services. JSON Schema: This allows you to validate JSON documents used in OpenAPI and AsyncAPIs. The specification is split into two parts — core and validation. The core defines the basic foundation and the validation defines the validation keywords of JSON Schema. |
What were the troubles?
The first thing the team focused on was the way the contract was sent to them. It found that the contract was defined loosely, and also error-prone. The documents shared by the client made the team go back and forth a lot of times. The business manager had to constantly keep in touch with the client to seek clarification about the pieces that were missing. It turned out that the first major challenge was not coding, but the way the two teams (client and developers) were communicating.
The integration, however, failed even after all the efforts, and the prime reasons for this, the team realised, included incorrectly spelt fields, mismatched data types, case sensitive fields, error parsing issues, missing responses, and more. In a nutshell, the errors arose as proper marking was not done by the client, and the contract was not used in the correct way.
The way to specifications
The journey to deliver better APIs using open source starts with “communicating APIs via specifications.” If the team developing a feature (or features) is able to understand the specifications better, it gets into a good position not only to develop, but also pass the requests to the entire community of developers better!
Next comes the clarity derived from schema objects, which are basically defined as logical structures created by users. Objects such as tables or indexes, which hold data in many cases, also consist of a definition. In the Dolby Media Analyze OpenAPI, RequestError is a schema object defined as shown in Figure 1.
Schema objects can be defined, and this will resolve the error response parsing issues the team faces. Figure 2 shows an example of a defined schema object. Schema validations on the specification help ensure at least one successful response is defined for a path. There can be a lot of other validations on the schema too. Tooling like documentation, code generation, mock servers can be used to support the specifications further.
These specifications, in short, act as a blueprint for APIs, which can be of great help in describing the overall structure of an API.
“Spreadsheets served us well in the information age, but as enterprises wrestle with their digital transformation, they are realising they need a much more precise set of human and machine-readable tools that can track the exponential increase in data being produced each day. These specifications now help teams keep up with the perpetual pace of change and remain competitive in today’s ever-evolving and shifting digital landscape,” says Postman chief evangelist Kin Lane.
This article is based on a talk given by Meenakshi Dhanani, developer advocate, Postman, at OSI 2021.
