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:
- 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).
- Open Postman.
- Select your collection.
- On the Authorization tab, configure settings as follows:
- Type = API Key
- Key = XpandAuthToken
- Value = [Your_secret_key_value] (it can be copied from the API client settings in Xpand Portal)
- 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:
- Open Postman.
- Select your collection.
- On the Authorization tab, set the Type setting to OAuth2.0.
- 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.
- Specify configuration options as follows:
- Token Name - Specifies the name of the token. You can enter any name here.
- Grant Type - Specifies the type of grant. Select Password Credentials
- 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)
- Client ID - Specifies the ID of the client. Type your client ID copied from the Xpand Portal API client settings.
- Client Secret - Specifies the secret key of the client. Type your client secret key copied from the Xpand Portal API client settings.
- Username - Specifies the username that will be used for authorization.
- Password - Specifies the password that will be used for authorization.
- Select the Get New Access Token button.
- When an access token is generated successfully, select the Use Token button.
- 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