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.

ImportantYou must only use the APIs mentioned in this documentation. All other APIs (not mentioned in the documentation) are subject to changes and using them in any process may cause unpredictable results.

221_DevAPI_RESTAPIwithSwagger.png


Related topics

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

Troubleshooting-issues-when-using-Swagger-as-a-REST-API-clientSwagger 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

For more information about Swagger RESTful API, see Swagger UI.

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

Follow the steps to authenticate the AR REST API:

  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 list, select JWTResource.
    image2019-1-9_14-51-52.png
  3. Click the /jwt/login API. 
  4. Click Try it out!. 
  5. Enter details such as username, 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 list in the top-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 box, enter AR-JWT, leave a space, and then paste the copied token.
  10. 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.


Unsupported parameter for macro: tags Due of this, the macro might have some unexpected results.

(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 menu is displayed:
    image2019-1-18_14-26-21.png
  5. Enter the client_iD and the client_secret for the client registered in your BMC Helix SSO admin console.
  6.  Click Authorize.
    A new browser window opens:
    221_DevAPI_RESTAPIwithSwaggerLogIn.png
  7. Enter the AR System login credentials, and click Log in. 
    After successful authentication, the following screen is displayed:
    221_DevAPI_RESTAPIwithSwaggerAuthorize.png
  8. Click OK.
    You are authorized through OAuth2 authentication.


 

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