KIBO OMS DOCUMENTATION

Using Postman

Postman is an API development application that facilitates the building and testing of API requests. Postman’s interface helps generate requests to ensure that they are structured appropriately and troubleshoot errors.

This guide covers the procedures for authenticating in Postman, building a request, and accessing additional information from resources like schemas and collections.

Authenticating in Postman

Authentication requests can be performed in Postman, as summarized below. If needed, refer to the Authentication guide for a more detailed explanation of this process.

First, acquire the API Key and Client Secret from the project manager. Then, encode them in Base64 with a “:” separator (e.g. API_KEY:SECRET_KEY). With the encoded credentials, create a POST request calling the proper OAuth server:

  • Production: https://auth.shopatron.com/oauthserver/oauth2/token
  • Staging: https://authstaging.cloudatron.com/oauthserver/oauth2/token
  • Development: https://authdev.cloudatron.com/oauthserver/oauth2/token

The encoded credentials should be included in the header in the form “Basic”, with a key name of “Authorization.” The body of the request should have the key = value pair of “grant_type = client_credentials.” The content type of the request should be “x-www-form-urlencoded.”

After sending the request, the response will provide the valid access token which can then be used to test other calls and requests.

Creating Requests

There are four sections to an API request:

  1. URL
  2. Method
  3. Header
  4. Body

URL

This is the unique address or endpoint for a resource, webpage, image, video, etc. Query parameters can be appended to the URL with a “?”, and multiple parameters can be separated with an “&” (any spaces, %, and other special characters in the parameters need to be URL encoded). Do not forget that the parameters are case sensitive.

OMS request URLs have the following base endpoints for the different environments:

  • Production – integration.shopatron.com
  • Staging – integrationstaging.shopatron.com
  • Development – integrationdev.shopatron.com

Method

The method is the action that the request would like the server to take (GET, POST, PUT, or DELETE). The method can be selected in the dropdown next to the URL in Postman.

Header

The header provides various parameters and meta-information about the request being made. The API Key and Authorization token should be in the header section of every request.

Body

The body contains data that is being sent to the server. Some requests, such as GET, do not require any information to be passed in the body. Others, such as POST or PUT, require information for the server to be passed in the body in a certain format and with certain parameters.

Variables

Variables can be added anywhere in a request (e.g. URL, header, body) and are denoted with {{ }}.

Add and manage variables by clicking the cog button and then “Manage Environments”. Then select “Globals” or the other appropriate environment for the variables.

Header Presets

Manage and create header presets for different clients and environments by clicking on the presets button next to the header values.

Schemas

Object schemas can also be accessed within Postman. Calling a schema returns any required parameters or values, additional information, and reference links that may be useful. An API Key or authentication is not needed to do this. Access a schema by going to the response header and copying the content-type profile. Append it to the URL and send the request.

Collections

Collections are organized groups of sample requests. They just need authentication and specific variables to be plugged in. When given a link for a collection, go to “Import” within Postman and select “Import from Link”, then enter the URL. Some of the guides on this site have links to relevant collections.


Megan MayfieldOMS Dev: Postman