Default language.

Using the REST API with Swagger

The REST endpoints exposed by the Remedy 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 End point documentation page.

Accessing AR REST API through Swagger UI

The Swagger UI shows a list of endpoints on a web page. You can read and submit requests after authentication. The following process explains how to access AR REST APIs through the Swagger UI.

You must enable CORS (Cross Origin Resource Sharing) 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. 


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

To download the Swagger UI

  1. In a web browser open the following URL:
    https://github.com/swagger-api/swagger-ui
  2. Click the Clone or download button and select the Download Zip option.
  3. Save the downloaded file to some location on your computer and extract the contents of the file.
  4. From the extracted folder, copy the dist folder and rename the dist folder to swagger-ui.

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

  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 JWTResouce.
    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 on the right hand 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 text-box, 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.

Using the RSSO_Oauth2 authentication with Swagger UI

If you have Remedy Single Sign-On (RSSO) installed, you can use the RSSO_Oauth2 authentication scheme through the Swagger UI. The following process explains how to access AR REST APIs through OAuth2 authentication.

image2019-2-18_13-18-28.png

Before you begin

Make sure that the Cross-domain requests are allowed on the Remedy SSO Server.

You can enable the Cross-domain requests on Apache Tomcat. For more information, see https://tomcat.apache.org/tomcat-7.0-doc/config/filter.html#CORS_Filter. An error occurs if Cross-domain requests are not enabled. 

Refer to the following code sample to enable to cross-domain requests.

To add the CORS filter, edit the web.xml file loacted in the TOMCAT_HOME/conf folder.

<filter>
 <filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
 <init-param>
   <param-name>cors.allowed.origins</param-name>
   <param-value>http://<Swagger Tomcat Hostname or IP>:<></param-value>
 </init-param>

 <init-param>   
<param-name>cors.allowed.methods</param-name>   
<param-value>GET,POST,PUT,DELETE,OPTIONS</param-value>
 </init-param>

 <init-param>   
<param-name>cors.exposed.headers</param-name>   
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
 </init-param>

 <init-param>   
<param-name>cors.support.credentials</param-name>
   <param-value>true</param-value>
 </init-param>
</filter>

<filter-mapping>
 <filter-name>CorsFilter</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

To register clients in the Remedy SSO Console

  1. Register the Swagger UI as a Remedy SSO client in the Remedy SSO Console. For more information, see OAuth Client Authentication
    image2019-2-18_8-52-3.png

  2. On the Remedy SSO Console, in the Redirect URI text box enter the following URL:
    http://<Swagger Tomcat Host Name or IP address>:<Tomcat HTTP port>/swagger-ui/oauth2-redirect.html
    The default port is 8080.

    Best Practice
    Use Localhost in the redirect URL. Use the Host Name or IP address of the computer where Swagger is running.

  3. Click Save.
    Copy the ClientSecret shown in the pop-up.

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.
    The default Jetty Server port is 8008.

    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"}
    ],
  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. Refer to the ClientSecret that you have saved.
  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 authorised through OAuth2 authentication.

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-Remedy-REST-API-clientSwagger RESTful API Documentation Specification

 

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