What is Postman?
Postman is an API platform for building, using, and testing APIs. It simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs faster. It does this by testing HTTP requests using a graphical user interface, where we obtain different types of responses that need to be subsequently validated.
Postman offers a couple of endpoint interaction methods. The following are some of the most used, including their functions:
- GET: Obtain information
- POST: Add information
- PUT: Replace information
- PATCH: Update certain information
- DELETE: Delete information
You can use Postman to submit data to an Ona form using the POST request. This is a HTTP method that allows you to send or push data to a server by including it in the body of the request. Whenever a POST request is submitted, there should be a change on the server receiving the data, such as updating, removing, or inserting.
Why use Postman to submit data?
Postman can be used when you have XML files for form submissions that you can not submit via Enketo or ODK Collect.
Postman is available on the web at go.postman.co/home and as a native desktop app for Mac (Intel & M1), Windows (32-bit / 64-bit), and Linux (64-bit) operating systems. You can also download the latest version of the Postman desktop app from this page.
To push data to Ona Data using Postman, you will need to follow the below steps:
Under the Collections section of Postman, select the Add a request option to begin creating the POST request.
Give your request a name. You can either leave it as New Request or give it another name.
Select POST on the method drop-down menu and paste the server URL: https://api.ona.io/api/v1/submissions
Under the Authorization section, select Basic Auth on the type drop-down menu. Then, enter your Ona account username and password.
Click on the Body section, and select form-data as your option. Form Data is used in sending data such as the details you enter when you fill out a form. These details are sent as KEY-VALUE pairs, where the key is the “name” of the entry you are sending, and the value is its associated content (file or text).
On the drop-down menu under the Key selection, select File and enter xml_submission_file. Ensure that the checkbox on the left side of the Key column is ticked.
Select your xml file in the Value section.
Then, click Send. A confirmation message will be displayed (201 Created) once the record has been successfully submitted.
Take a look at the video tutorial below to see this step-by-step process.
Status Codes
When testing APIs with Postman, we usually obtain different responses or status codes. These status codes are used to identify what may have gone wrong or where you made a mistake. Below are a few of the standard status codes on Postman:
- 200: Successful request.
- 201: A successful request. Data was created.
- 204: Empty response.
- 400: Bad Request. If you enter something incorrectly or you did not include some required parameters, the request is not understood by the server, and you will get the 400 status code.
- 401: Unauthorized Access. If the request authentication fails or the user does not have permission for the requested operations, then you will get a 401 status code.
- 403: Access Denied.
- 404: Data Not Found.
- 405: This status code will be returned if the method is not allowed or the requested method is not supported.
- 500: Internal Server Error.
- 503: Service Unavailable.