Using API in the Postman tool

To get data from or send data to Xpand Portal, you can use various API application clients.

In this topic, the Postman tool is used as an example to visualize interaction with the Xpand Portal API’s resources to retrieve/send data from/to Xpand Portal. To use this tool, it must be downloaded and installed on your PC. For more information about Postman, see Postman documentation.

Ensure that your API client is configured in Xpand Portal. If you are a portal member, you must also be allowed to use Xpand Portal API. 

Setting up authorization methods

You can use authorization through API key or use OAuth 2.0 authentication:

API Key

To set up authorization via API key:

  1. Make sure that you have disabled Enable OAuth 2.0 authorization on your API client (the Enable OAuth 2.0 authorization switch must be disabled in the API settings for the corresponding API client).
  2. Open Postman.
  3. Select your collection.
  4. On the Authorization tab, configure settings as follows:
    1. Type = API Key
    2. Key = XpandAuthToken
    3. Value = [Your_secret_key_value] (it can be copied from the API client settings in Xpand Portal)
  5. On all your added methods, on the Authorization tab, set the Type setting to Inherit auth from parent.

 To set up API key authorization open Postman API, select your collection and select Authorization Tab 

OAuth2.0

If additional OAuth 2.0 authentication is enabled for your API client in the Xpand Portal API client settings, you need to authorize through OAuth 2.0 authentication.

To set up OAuth2.0 authorization:

  1. Open Postman.
  2. Select your collection.
  3. On the Authorization tab, set the Type setting to OAuth2.0.
  4. In the section Configure new token, select the Edit token configuration button.

      Note

    The button and its description are available only when you configure the token for the first time.
  5. Specify configuration options as follows:
    1. Token Name - Specifies the name of the token. You can enter any name here.
    2. Grant Type - Specifies the type of grant. Select Password Credentials
    3. Access Token URL - Specifies the URL of the access toke, Fill in this field with https://your_portal_name/oauth/token> where your_portal_name is the domain of your Xpand Portal (Example: https://demo.xpandsoftware.com/oauth/token)
    4. Client ID - Specifies the ID of the client. Type your client ID copied from the Xpand Portal API client settings.
    5. Client Secret - Specifies the secret key of the client. Type your client secret key copied from the Xpand Portal API client settings.
    6. Username - Specifies the username that will be used for authorization.
    7. Password - Specifies the password that will be used for authorization.
  6. Select the Get New Access Token button.
  7. When an access token is generated successfully, select the Use Token button.
  8. On all your added methods, on the Authorization tab, set the Type setting to Inherit auth from parent.

Operations

The following methods that can utilize Xpand Portal API are available in Postman:

Method Description Learn more Example
HEAD: /api/1.0/Entities  Used to test connection and ensure that Xpand Portal API is configured properly.  Learn more Example
GET: /api/1.0/Entities/Info  Returns information about a known portal entity(ies). Learn more Example
GET: /api/1.0/Entities/Setup  Returns detailed information about entity setup, including setup values. Learn more Example
POST: /api/1.0/Entities/Data/{page}  Returns data from a portal grid page. Learn more Example
POST: /api/1.0/Entities/DataById/{query}/{page}  Returns data from a record on a portal grid page. Learn more Example
POST: /api/1.0/Entities/Update/{page}  Updates data in a specific record in Xpand Portal.  Learn more Example
PUT: /api/1.0/Entities/Create/{page} Creates a record in Xpand Portal.  Learn more Example
DELETE: /api/1.0/Entities/Remove/{page}  Deletes a record in Xpand Portal. Only data created by you can be deleted. Learn more Example
POST: /api/1.0/Entities/Sync/Store  Updates multiple records of an entity specified in the query. Learn more Example
POST: /api/1.0/Entities/Sync/Get  Returns records of an entity based on the specified query. Learn more Example

To learn about HTTP request, request header, parameters, and body of each method, select the Learn more link next to it. To see an example of usage (request and response) in Postman, select the Example link.

Method usage examples

HEAD: /api/1.0/Entities

Request example

Response example

GET: /api/1.0/Entities/Info

Request example


Response example

GET: /api/1.0/Entities/Setup

Request example


Response example

POST: /api/1.0/Entities/Data/{page}

Request example



Response example

POST: /api/1.0/Entities/DataById/{query}/{page}

Request example


Response example

POST: /api/1.0/Entities/Update/{page}

Request example



Response example

PUT: /api/1.0/Entities/Create/{page}

Request example



Response example

DELETE: /api/1.0/Entities/Remove/{page}

Request example


Response example

POST: /api/1.0/Entities/Sync/Store

Request example


Response example

POST: /api/1.0/Entities/Sync/Get

Request example


Response example