Communicating API problems between teams using cURL
APIs are everywhere
So in the modern software world, APIs are ubiquitous, be it in the integration layer of the application which external parties invoke or your front end dev/mobile app teams who consume similar or a different set of APIs to power their user interfaces.
Sometimes as we roll out newer changes on the existing APIs with additive changes or add new APIs serving a newer functionality, there is a problem of a wrong/unexpected response which teams have to communicate about.
Communicating the issue
We often have swagger/openAPI portals where different teams can try the API and observe the differences between the sample response and the actual response returned.
Some time ago I was working with a mobile app team who had problems with some of the API calls they were making. Whenever they had an issue, they raised an issue about a particular API response wasn’t matching what they were expecting. Sometimes they would indicate the parameters and data sent and many times they did not just throwing the issue over the wall.
As a backend developer, you would have go back to swagger page or post man, put in the same inputs/collect the inputs from the mobile team to compose the request and then check the response before and after the fix. This is a time consuming approach which requires effort in reproduction of the problem rather than solving the problem.
Imagine many such requests with request parameters, composing the request body just to reproduce the problem.
Solution — cURL it
We wanted to save the time it took us to reproduce the issue. For that to happen, there needs to be a way where mobile team sends us the exact request which we could further replay and test the response out.
The solution we found was to talk in terms of cURL between teams. cURL is the representation of the request along with the parameters and the request body sent to the resource (in case of a POST or PUT). This can be easily generated in Postman or in a swagger portal.
Ex: In case of postman, after the request is tried out, click the code icon to see the corresponding cURL request generated on the right.
The mobile team sent these cURL requests to back end team either as a file or as raw text over teams/slack or put them on the tickets. The backend teams can reproduce it by importing the cURL request into postman using the import functionality.
I’m importing the cURL request shown in the screen above as raw text.
Hit continue and your request is ready to be replayed.
This gave us the entire request made from the mobile app without us sweating effort on collecting the data required for the request resulting in quicker diagnosis and resolution of the problems. Win — win for both teams.
Summary
Finding solutions which work between different teams is extremely important to move the needle on projects. I’m glad cURL helped us in this regard and set a standard for communication for APIs.
