Using API in the SWAGGER UI tool
To get data from or send data to Xpand Portal, you can use various API application clients.
In this topic, the SWAGGER UI tool is used as an example to visualize interaction with the Xpand Portal API’s resources to retrieve/send data from/to Xpand Portal. For more information about Swagger, see the Swagger documentation portal.
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.
Accessing SWAGGER UI
To open the SWAGGER UI tool for Xpand Portal, use the following URL:
https://<frontend_domain_name>/swagger/
where <frontend_domain_name> is the domain name that portal members (end users) use to access the Xpand Portal front end. Thus, you basically need to add /swagger/ to the Xpand Portal URL.
To be able to use Xpand Portal API, in the api_key field, enter your API secret key, and then select Explore. For portal members, the administrator can generate an API secret key in the member settings when enabling access to API for a portal member.
Select Entities or Show/Hide to see the list of available operations.
Select an operation name to expand or collapse it. To expand all operations, select Expand Operations. To collapse all operations, select List Operations.
Additional OAuth 2.0 authentication
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: select the icon in the expanded form of an API operation, and enter the following:
- Username – Specifies the name of the Xpand Portal CMS user that will be used to authenticate this API client.
- Password – Specifies the password of the Xpand Portal CMS user that will be used to authenticate this API client.
- Type – Specifies the type of authentication.
- ClientId – Specifies the application client ID that was configured for this API client in the Xpand Portal API clients settings (Media > Portal Settings > OAuth & SSO Settings > API clients tab; the Client application ID field) for this client. This field becomes available after you select an authentication type.
- Secret – Specifies the password that was configured for this API client in the Xpand Portal API clients settings (Media > Portal Settings > OAuth & SSO Settings > API clients tab; the Secret key field). This field becomes available after you select an authentication type.
Note
The password that was specified the Secret key field in the Xpand Portal API clients settings is automatically transformed into a secret key after saving the settings. However, in the Secret field on this form, you must enter the password of the client.
Select Authorize to perform OAuth 2.0 authorization.
Note This applies to all operations, except HEAD: /api/1.0/Entities. |
Operations
The following methods that can utilize Xpand Portal API are available in SWAGGER UI:
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 Swagger UI, 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