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.

Using API in the SWAGGER UI tool

Accessing SWAGGER UI

Additional OAuth 2.0 authentication

Operations

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