Postman Tutorial
This tutorial will guide you through the installation of Postman API analyzer and how to test your Signed mTLS Certificate files and your API Keys.
We recommend that developers use our sandbox environment for IT tests, integration tests and initial data push/pull tests.
To get started, download the Postman app: https://www.postman.com/downloads/
Click the download button to install the Postman App, then follow the instructions to configure Postman on your machine
Once it is installed, continue to the next tutorial to configure mTLS
Please Note:
The download button will show the required version you need for your specific operating system.
Go to the Gear Icon and click 'Settings' in Postman
Click on the 'Certificates' tab and then 'Add Certificate'
Enter the following information:
- Host - Enter the host for the environment you would like to access
- CRT File - This is your xecta-data-api.pem
- KEY File - This is your xecta-data-api.key
Your signed certificate (PEM and KEY) is generated as part of the mTLS & API Key Creation tutorial
For the tutorial screens below, use the following REST URLs for the host baseURL:
Stage Environment: data-stage.onxecta.com
Production Environment: data.onxecta.com
Last step is to click the 'Add' button
Download the OAS file to import into Postman here: Production OAS File
Once you download the OAS file, import the project into Postman. To do this:
- Click on the APIs Tab
- Click 'Create an API'
- Click the Import Button
- Select the file which you had downloaded from the GitHub repo listed above
- Click the Import Button to finalize the import
Now you should see the project imported into Postman and you can begin looking at the endpoints
To begin, start a new empty POST request with the URL: https://prod.authenticate.onxecta.com/oauth2/token?grant_type=client_credentials
Verify in the Params tab that there is a KEY entry for grant_type with a value of client_credentials
Next, click the Authorization tab and select Basic Auth
Here you will input your Client ID for the Username, and Client Secret as the password. These were provided to you via SendSafely
The above Username is a fake generated Username for instruction purposes only. It does not tie to any App Client in AWS Cognito
Next, navigate to the Headers tab. You will need to add a Content-Type Header with the value application/x-www-form-urlencoded as shown below
Now you are all set up! Click the Send button and you will get an access token returned if everything was set up correctly. It will look similar to this below
The final step is to run a query against the Xecta API.
Copy the Access token from the step above and open an API endpoint from the left side, which was imported into Postman previously
Set the URL to point to the Production Environment: https://data.onxecta.com
Navigate to the Authorization tab, and select the Bearer Token Type from the drop down
Paste your previously generated Access token into the Token field here
Click Send, you should get a 200 OK response
You are now fully connected to the Xecta API!
The following sections provide specific examples to accomplish various tasks with the API endpoints.
GET requests retrieve data already imported into the system
Uncheck Query Params of "offset" and "limit"
Insert value for Path Variable - uwi
- Example: uwi: enim
- Empty results with 200 OK response will be returned if queried uwi doesn't exist in database
Insert value for Path Variable - uwi
- Example: uwi: enim
- Empty results with 200 OK response will be returned if queried uwi doesn't exist in database
POST requests allow you to submit data for import
In Body, specify data to be added to the Well
200 OK response returned when data has been successfully added/ updated to Well
In Body, specify data to be added to the Daily Production
- uwi of new data has to exist in Well, otherwise 400 Bad Request response will be returned
Delete requests allow you to remove data previously imported into the system
Insert value for uwi. 200 OK returned if data has been deleted successfully; 400 Bad Request returned if uwi doesn't exist in database.
Insert value for xid. 200 OK returned if data has been deleted successfully; 400 Bad Request returned if xid doesn't exist in database.
