Scroll

Getting Started with REST

This guide serves as a step-by-step walkthrough for installing and configuring the REST Web Service, verifying that it is working properly, and briefly demonstrating how it works.

Table of Contents

  1. Install the Web Service API
  2. Set up the App Pool
  3. Set up File Permissions
  4. Check the Connection
  5. Point the Web Service to Exago
  6. Enable REST
  7. Test Creating a Session
  8. Test Modifying a Session
  9. Test Launching a Session
  10. Adding Authorization

Install the Web Service API

Download the Exago installer that corresponds with your version of the Exago application. Run the installer with administrative privileges. Click the center button to install the Web Service API.

rest_install.png

Click Next, then on the Select Installation Location screen, do the following:

  1. Select a Web Site.
  2. Enter a virtual directory path. This will be the URL that REST requests are made to. This is different from the Exago Web App virtual path.
    Note: We will refer to this path by the placeholder text "web_service_virtual_path".
  3. Select a physical directory path to install the files. This should not be inside a managed directory such as Program Files or Windows.
    Note: We will refer to this path by the placeholder text "web_service_physical_path".

Click Next and wait for the installation to conclude. Then click Finish.

If the installation failed, then the installer may have been trying to install to a location without sufficient privileges, or overwrite files which were locked by a system process. Try again with a different file path.

Set up the App Pool

Open IIS (Internet Information Services). In the left pane, expand the Web Site that you selected in the installation, then locate and select the virtual path you selected for the Web Service API.

Also write down the virtual path of the Exago Web Application, for later.
Note: We will refer to this path by the placeholder text "web_app_virtual_path".

In the right pane, click Advanced Settings....

For Application Pool, click the ellipsis [...] icon on the right, then select an app pool with .NET CLR version 4.0 and Pipeline Mode: Integrated. (This is often the same app pool as the Web App). Click OK.

For Enabled Protocols, enter "http" (without quotes) if it is not already there. Click OK.

In the left pane, click Application Pools. Write down the identity of the app pool you just selected. If it is "ApplicationPoolIdentity", write down IIS_IUSRS instead.

Set up File Permissions

Navigate to the Web Service API physical directory path (the installation path). Right-click the folder and select Properties. Then click the Security tab.

Click Edit, then Add.... Type the app pool identity into the "Enter the object names to select" field, then click OK.

Select this identity, then in the Permissions pane, select the Allow checkbox for Full Control. Click OK, then click OK again to save your changes.

Check the Connection

In a supported web browser, enter the following URL:

http://localhost/webservice_virtual_path/Api.asmx

Note: localhost depends on the website name and port number of the IIS Web Site that the Web Service was installed to. If localhost does not work, you can try 127.0.0.1 instead.

If you can successfully navigate to this page, then IIS is configured correctly. If not, check your IIS, network, and firewall settings, or contact your network administrator.

Point the Web Service to Exago

In the Web Service API directory, open the following file in a text editor:

web_service_physical_path/Config/WebReportsApi.xml

Locate the <apppath></apppath> nodes and enter the Web App (NOT the Web Service) virtual path in between:

<apppath>http://localhost/web_app_virtual_path</apppath>

Save the file. Then restart the IIS Web Server.

In your web browser, refresh the Api.asmx page.

Click InitializeApi, then click Invoke.

The web service path is configured correctly if the resulting page looks similar to the following:

<string xmlns="http://www.exagoinc.com/">
8GIXsZca2PHBlS3k2J/7gfwKggMdftbRkro0zIXTjMFSUlj03cBe3cvel+DGUbWjRbgNt3srJ8f0GYXwgaD/QQ==
</string>

If the page looks like the following, then the web service cannot locate the Exago Web App:

<string xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.exagoinc.com/" xsi:nil="true"/>

Check that the path was entered correctly in the configuration file.

Once you have successfully connected, locate and delete the following file in the Web Service API directory:

web_service_physical_path/Bin/api.asmx.cdcab7d2.compiled

This will disable the outdated SOAP API and Api.asmx test file.

Enable REST

In the Web Service API directory, open the following file in a text editor:

web_service_physical_path/appSettings.config

Locate the <appSettings></appSettings> nodes and add the following text in between:

<add key="ExagoREST" value="True" />

The result should be the following:

<?xml version="1.0"?>
<appSettings>
  <add key="ExagoREST" value="True" />
</appSettings>

Then restart the IIS web server again.

Test Creating a Session

Open Advanced REST Client, Postman, or another REST client application.

For Method, select POST. Enter the following Request URL:

http://localhost/webservice_virtual_path/rest/sessions

If your config file is NOT "WebReports.xml", then use the following URL:

http://localhost/webservice_virtual_path/rest/sessions?config=fileName
Note: fileName is case sensitive, WITHOUT the ".xml" or ".xml.enc" file extension.

Enter the following request headers:

accept: application/json
content-type: application/json
authorization: Basic Og==

Click Send.

If the request succeeded, you will receive a Response Code: 201 Created, and the following text in the response payload:

{
  "AppUrl": "UrlParamString",
  ...
  "Id": "1234-5678-9012-3456",
  ...
}

When you have successfully returned a 201 response code and a valid body, find the AppUrl and Id fields, and copy down their values. You can safely ignore the other fields for now.
Note: We will refer to the Session ID by the placeholder text 1234-5678-9012-3456.

Troubleshooting

500 Internal Server Error
"reason" : "Unauthorized" or "Invalid length for a Base-64 char array or string"

500 Internal Server Error
"reason" : "Unable to load configuration"

  • Configuration file URL parameter is incorrect.

500 Internal Server Error
<HTML response payload>

  • Request URL path is misspelled or mistyped, or REST is not enabled.

404 Not Found
<HTML response payload>

  • Method is incorrect (should be POST), or Request URL path is incorrect.

Connection Refused

  • Server is down or behind a firewall. Make sure the web server restarted properly after enabling REST.

Test Modifying a Session

Now you can familiarize yourself with the functionality of the REST interface. Let's make a simple change to the session, such as changing the language to Spanish.

In the REST client, change the Method to PATCH. Change the request URL to the following:

http://localhost/webservice_virtual_path/rest/settings?sid=1234-5678-9012-3456

The sid is the "Id" returned from the initial POST /sessions request.

Enter the following text in the request payload:

{
  "General" :
  {
    "LanguageFile" : "es-mx,es-mx-getting-started,es-mx-tooltips"
  }
}

Click Send.

If the request succeeded, you will receive a Response Code: 204 No Content, with an empty payload.

Troubleshooting

500 Internal Server Error
"reason" : "setupD is null"

  • Session ID is incorrect.

500 Internal Server Error

  • JSON may not have been formatted correctly. Examine the "reason" field in the response payload to see the specific error message.

Optional: Verify the Settings Change

Change the method to GET. Click Send.

If the request succeeded, you will receive a Response Code: 200 OK, and the following text in the response payload:

{
  "LanguageFile" : "es-mx,es-mx-getting-started,es-mx-tooltips",
  ...
}

If this value still shows "en-us,en-us-getting-started,en-us-tooltips", then you may have mistyped "LanguageFile" in the PATCH request. Verify that the property name was spelled and capitalized correctly.

Test Launching a Session

Locate the UrlParamString (AppUrl) that you copied down from the initial POST /sessions request.

In a web browser, navigate to the following URL:

http://localhost/web_app_virtual_path/UrlParamString

(Where everything after /web_app_virtual_path/ is the UrlParamString).

If everything succeeded, the browser should launch the Exago user interface in Spanish. ¡Olé!

Troubleshooting

An error has occurred. Please contact your administrator.
Error reading configuration file.

  • Your config file is using a temp directory that is different from that of the default (in WebReports.xml), or you may have accidentally used the wrong web reports app path (such as for an older installation of Exago).

Note on Session Closure

Once the session has been launched in the browser, it has been converted to a user session, and can no longer be accessed or modified by the REST API. To demonstrate, you can attempt to access the session again using the session ID and any endpoint. You will receive a 500 error if you attempt to modify a closed session.

Adding Authorization

Open the Exago Web App configuration file in a text editor (Note: If you have multiple config files, they all need to be secured in this manner, or else someone could simply bypass authorization by specifying a different config file upon session creation).

web_app_physical_path/Config/ConfigFile.xml

Or open the Admin Console and select the config file from the dropdown menu in the top-left:

http://localhost/web_app_virtual_path/Admin.aspx

Under Other Settings, add a REST Key, or click Generate to create a random one. (Optional) Add a User Id as well.

Click Apply or Okay.

Now you need to generate the authorization header based on these two fields.

Go to the website http://base64encode.org/ or use another way to encode a string in base 64.

Enter the following in the form:

UserId:RestKey

These are the User Id and Rest Key values added in the previous step. Note the colon (:) in between. If you left the User Id blank, use :RestKey instead.

Click Encode as UTF-8. Copy down the resulting string.

In ARC or Postman, replace "Og==" with the encoded result string in the Authorization header.

authorization: Basic EncodedAuthString

Change the method to POST and set the Request URL to the following:

http://localhost/webservice_virtual_path/rest/sessions

(Append ?config=fileName if necessary.)

Click Send.

If the request succeeded, you will receive a Response Code: 201 Created. You have successfully added Basic authorization. For an alternative authorization method, see ExagoKey Authorization.

Make sure that all your config files have a REST Key.


Hidden Article Information

Article Author
Exago Development
created 2018-06-04 16:44:42 UTC
updated 2018-06-04 21:43:04 UTC

Labels
IIS, config, troubleshooting, web, service, header, method, tutorial, walkthrough, api, url, key, rest, setup, intro, how-to, help,
Have more questions? Submit a request