POSTMAN for ‘API CONTRACT’
Well, let’s start with the definition.
What is API contract?
It is something that both API provider and API consumer can agree upon, and get to work developing , delivering, integrating and finally consuming. An API contract is a shared understanding of what the capabilities of a digital interface are, allowing for applications to be programmed on top of. — API EVANGELIST
Why we need API Contract ?
When our “business guy” or whoever they are, define the business rules, most of us still have our own imagination.
Lets assume this scenario like this
‘Business-guy’ (BG )
‘Server-guardian’ (SG )
‘Frontend-man’ ( FM )
BG : The order page can be rejected by our customer, so our customer can re-order till they get the highest promotion from our vendor.
SG : oh oke , we can do that.
FM : alright, piece of cake.
meeting end.
SG and FM discuss in different meeting,
SG : I will use ‘long’ instead of ‘date’ for this ‘field’
FM : OK..OK.
and vice versa
This shows a common mistake happen in product development process as our SG and FM discussed among themselves in different forum, while the discussions were not documented by BG.
Mostly on small team, documentation is used for business needs, while on technical side the changes in API are rarely well documented. All stake holder needs to know that theres are changes in API. Therefore, a well-detailed API documentation is required to make sure they know and for next changes you could use API changes strategy.
For efficiency, we need simple tools to document the change and postman is one of them.
- You have to manage the collections
2. Create your request
this will be our contract.
3. Create an example
At right top , you will see “examples”
in this case, we just created 2 examples, one for validation and one for success response, but you can create as many as you need.
4. Make sure your examples is right
Click one of your “examples” and then you need to define all your HTTP request-response
4.1. Define your request
lets run this scenario, if our client send this kind of data
RequestHeader
RequestBody[
{
"description": "discount may 2020",
"validFrom": "2020-05-01",
"validThrough": "2020-05-15",
"applyTo": 1,
"segmentation": {
"marketSegment": "MT",
"channel": "Minimarket",
"subChannel": "Minimarket local"
},
"rules": [
{
"moreThan": 100000,
"getDiscount": 1
},
{
"moreThan": 200000,
"getDiscount": 2
},
{
"moreThan": 300000,
"getDiscount": 5
}
],
"recordStatus": "A"
}
]
What will you do ?
4.2. Define your response based on request
If our client send exact data then reponse status will be “400 Bad Request” and JSON payload
{
"code": "400-V_PROPERTIES",
"description": "Terjadi kesalahan pada properties yang dikirim",
"additionalEntity": {
"result": {
"errorValidation": {
"discountId": "tidak boleh kosong"
}
}
},
"defaultInfos": null
}5. Share your collection
There are 2 way to share collection
first, we use feature ‘workspace’ in postman or manually export and share it.
finally, your team can import this collection to their postman
6. Mock collection
You can create a mock in several ways in the Postman app:
* Using the New button
* From the Launch screen
* Using Examples in an existing collectionPostman documentation
When you create your mock server, you will get
after this you can try it, just send a request to response ‘URL’
Releasing contract means we should be able to work in parallel. QA could create automation test for our API , Backend could develop based on contract, and Frontend could create UI based on contract. If we could work this in harmony, we would have a happy ending.
We did some implementation in our team and the communication is getting better.