This documentation supports the 19.02 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

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.

The Swagger.json file

The Swagger specification of the REST API consists of a JSON file called swagger.json. This file includes endpoint URLs, descriptions, request parameters, and response structures. Defining the endpoints in this standard, machine-readable format enables the use of automated tools such as interactive documentation and client code generation.

Because each version of the REST API has its own list of endpoints, there is one swagger.json file per version. For example, the specification of the endpoints in version 1.0 of the API can be found at:

/api/v1.0/swagger.json

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. For more information, see Configuration settings A-B


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 index.html file. 
  3. In the index.html file, search for SwaggerUIBundle.
  4. Replace the url section below the SwaggerUIBundle with the following URL details:

    [
    {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"}
    ],

    The default Jetty Server Port is 8008.

  5. (Optional) Turn off the Swagger schema validation by adding validatorUrl: null, in the SwaggerUIBundle object of the index.html file.

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.
  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.
  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 End points 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.


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

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

    [{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"}],

    The default Jetty Server port is 8008.

  3. Refresh the browser. 
  4. Click Authorize.

    The following pop-up is displayed.
  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. 
  7. Enter the AR System login credentials. Click Log in.
    After successful authentication, the following screen is displayed.
  8. Click OK. You are now authorised through OAuth2 authentication.

Related topics

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

End points in AR REST API


Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Anders Wilhelm

    Am I correct in assuming that the Swagger/OpenAPI-specification is version 2.0?

    Mar 03, 2019 01:03
    1. Rudrangshu Das

      Hello Anders,

      Yes, the  Swagger/OpenAPI-specification version is 2.0.

      Regards,

      Rudrangshu

      Mar 04, 2019 01:00
  2. Anders Wilhelm

    Typo? 1)To authenticate the AR REST API

    Open the following URL in the web browser: http://:<8008>/swagger-ui/

    Shouldn't that point to the tomcat server and the swagger-ui web app?

    Mar 15, 2019 03:40
    1. Anagha Deshpande

      Hello Anders,

      Thanks for bringing this to our notice.

      We have corrected the topic.

      Regards,

      Anagha

      Mar 18, 2019 01:39
  3. Karthick Krishnan

    is the Swagger UI support applies to older versions of remedy (or) is it a newly introduced feature for 19.02 upwards?

    May 22, 2019 09:46
    1. Anagha Deshpande

      Hello Karthick,

      Using Swagger UI is a new feature introduced in version 19.02. It is available for Remedy AR System version 19.02 and later.

      Regards,

      Anagha

      May 22, 2019 10:32