Using the REST API with Swagger
The REST endpoints exposed by the AR System server are documented by using Swagger specifications. This topic provides guidelines for using Swagger UI. In addition to the Swagger UI, you can view the endpoints provided by this REST API in the Endpoints-in-AR-REST-API.
Before you begin
Download the Swagger UI.
To access the AR REST API through Swagger UI
Enable Cross Origin Resource Sharing (CORS) on the AR System server.
The CORS headers are configured as Centralized Configuration settings:- Access-Control-Allow-Credentials
- Access-Control-Expose-Headers
- Access-Control-Allow-Headers
- Access-Control-Allow-Methods
- Access-Control-Allow-Origin
For more information, see Configuration-settings-A-B.
Replace the url section below the SwaggerUIBundle with the URL details having the following syntax:
urls: [
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-jwt.json", name:"JWTResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-entry.json", name:"EntryResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-fields.json", name:"FieldsResource"}
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-menu.json", name:"MenuResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-webhook.json", name:"WebhookResource"}
],For example:
urls: [
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-jwt.json", name:"JWTResource_Name"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-entry.json", name:"EntryResource_Name"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-fields.json", name:"FieldsResource_Name"}
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-menu.json", name:"MenuResource"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-webhook.json", name:"WebhookResource"}
],The default Jetty server port is 8008.
For more information, see Knowledge Article number 000253769 (Support logon ID required).
To deploy Swagger UI in a Web server
For more information about Swagger RESTful API, see Swagger UI.
Make sure you have installed your own web server, and then perform the steps based on the following example for Windows-based Tomcat installation:
- Move the swagger-ui folder from your custom location to Tomcat\webapps folder.
For example: C:\Program Files\Apache Software Foundation\Tomcat7.0\webapps - From the swagger-ui folder, open the swagger-initializer.js file.
- In the swagger-initializer.js file, search for SwaggerUIBundle.
Replace the url section below the SwaggerUIBundle with the URL details having the following syntax:
urls: [
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-jwt.json", name:"JWTResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-entry.json", name:"EntryResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-fields.json", name:"FieldsResource"}
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-menu.json", name:"MenuResource"},
{url:"http://<AR Server IP address>:<Jetty Server Port>/api/arsys/v1.0/swagger/ars-webhook.json", name:"WebhookResource"}
],For example:
urls: [
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-jwt.json", name:"JWTResource_Name"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-entry.json", name:"EntryResource_Name"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-fields.json", name:"FieldsResource_Name"}
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-menu.json", name:"MenuResource"},
{url:"http://ARSERVER:8008/api/arsys/v1.0/swagger/ars-webhook.json", name:"WebhookResource"}
],The default Jetty server port is 8008.
- (Optional) Turn off the Swagger schema validation by adding validatorUrl: null, in the SwaggerUIBundle.
To authenticate the AR REST API
If you do not use BMC Helix Single Sign-On, use the following procedure to authenticate the API. (If you use BMC Helix Single Sign-On, do not follow this procedure. Instead, see Enabling-OAuth-authorization-for-AR-System-REST-APIs.)
Follow the steps to authenticate the AR REST API:
- Open the following URL in the web browser:
http://<localhost>:<Tomcat port>/swagger-ui/
The default Tomcat port is 8080. - From the Select a definition list, select JWTResource.
- Click the /jwt/login API.
- Click Try it out!.
- Enter details such as username, password, and then click Execute.
Status code 200 is displayed. - Copy the text in the Response body.
The copied text is a token to authenticate REST APIs. - From the Select a definition list in the top-right corner, select EntryResource (for entry APIs) or FieldsResource (for field APIs).
- Click Authorize.
The Available authorization dialog box is displayed.
- In the Value box, enter AR-JWT, leave a space, and then paste the copied token.
- Click Authorize and close the dialog box.
You can access any AR REST API by entering relevant field information. For more information, see Endpoints-in-AR-REST-API.