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 Endpoints-in-AR-REST-API.

image2019-1-10_8-47-8.png

Related topics

Integrating-AR-System-forms-with-a-third-party-application-by-using-the-REST-API

Endpoints-in-AR-REST-API

Troubleshooting-issues-when-using-Swagger-as-a-REST-API-client
Swagger RESTful API Documentation Specification

Before you begin

Download the Swagger UI.

To access the AR REST API through Swagger UI

  1. 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. 

  2. 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 container

The following procedure explains how to deploy Swagger UI in Apache Tomcat.

  1. Move the swagger-ui folder from your custom location to Tomcat\webapps folder. 
    For example, C:\Program Files\Apache Software Foundation\Tomcat7.0\webapps
  2. From the swagger-ui folder, open the swagger-initializer.js file.
  3. In the swagger-initializer.js file, search for SwaggerUIBundle.
    SwaggerUI.png

  4. 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.

  5. (Optional) Turn off the Swagger schema validation by adding validatorUrl: null, in the SwaggerUIBundle.

    image2019-3-28_12-15-53.png

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.)

  1. Open the following URL in the web browser:
    http://<localhost>:<Tomcat port>/swagger-ui/ 
    The default Tomcat port is 8080.
  2. From the Select a definition drop-down, select JWTResource.
    image2019-1-9_14-51-52.png
  3. Click on the /jwt/login API. 
  4. Click Try it out!. 
  5. Enter details such as username and password and then click Execute. 
    Status code 200 is displayed.
  6. Copy the text in the Response body. 
    The copied text is a token to authenticate REST APIs.
  7. From the Select a definition drop-down in the upper-right corner, select EntryResource (for entry APIs) or FieldsResource (for field APIs). 
  8.  Click Authorize. 
    The Available authorization dialog box is displayed.
    image2019-1-9_21-19-29.png
  9. In the Value field, enter AR-JWT, space, and paste the copied token.
  10. Click Authorize and close the dialog box.

You can now access any AR REST API by entering relevant field information. For more information, see Endpoints-in-AR-REST-API.

(On-premises deployments) To configure OAuth authentication in the Swagger UI

  1. Add the following attribute in the index.html file, located in the swagger-ui folder.
    oauth2RedirectUrl: window.location.origin +"/swagger-ui/oauth2-redirect.html"
    image2019-2-18_10-43-13.png

  2. Replace the url attribute below the SwaggerUIBundle with the following URL details.

    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>:<c>/api/arsys/v1.0/swagger/ars-entry.json?rssoUrl=
     http://<rsso server ip>:<RSSO Jetty Server port>"    ,name:"EntryResource"},                   
    {url:"http://<AR Server IP address>:<Jetty Server port>/api/arsys/v1.0/swagger/ars-fields.json?rssoUrl=
     http://<rsso server ip>:<RSSO Jetty Server port>"    ,name:"FieldsResource"}
    {url:"http://<AR Server IP address>:<Jetty Server port>/api/arsys/v1.0/swagger/ars-Menu.json?rssoUrl=
     http://<rsso server ip>:<RSSO Jetty Server port>"    ,name:"MenuResource"}
    {url:"http://<AR Server IP address>:<Jetty Server port>/api/arsys/v1.0/swagger/ars-Webhook.json?rssoUrl=
     http://<rsso server ip>:<RSSO Jetty Server port>"    ,name:"WebhookResource"}
    ],

    The default Jetty Server port is 8008.

  3. Refresh the browser. 
  4. Click Authorize.
    Authorize.png
    The following pop-up is displayed.
    image2019-1-18_14-26-21.png
  5. Enter Client ID and ClientSecret for the client registered in your Remedy SSO admin console.
  6.  Click Authorize.
    A new browser window opens. 
    screen1.png
  7. Enter the AR System login credentials. Click Log in. 
    After successful authentication, the following screen is displayed.
    image2019-2-18_10-57-22.png
  8. Click OK.
    You are now authorized through OAuth2 authentication.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*