Verifying Application Endpoint URLs

AMS can test an app's endpoint URLs to ensure they are all reachable. This feature enables app developers to test whether or not AMS can reach their app's endpoints prior to deploying apps. This feature also provides a method to troubleshoot app connectivity issues.

AMS tests your app's endpoints URLs by sending an OPTIONS request. This test supports the endpoints: Install URL, Uninstall URL, Configure URL, Save Configure URL, and Status URL.

To access the URL verification test:

  1. From the AMS home page, select an app.
  2. Click URL Verification.

When all endpoints can be successfully reached, the test should resemble the following:

Note: The Status URL will not be reachable because that endpoint is not currently implemented within AMS.

In this topic:

Request details

AMS sends the following request.

Request method

OPTIONS

Authentication: JWT

Example claim

{
  "iss": "AMS",
  "sub": "87f93929-0566-4f6d-a2d9-ad28ee07dd86",
  "aud": "7415ef49-f47a-4c02-94f2-0523d896ae50",
  "exp": 1545080150,
  "iat": 1545080090,
  "jti": "b319d354-7c1d-46b9-add0-bf40b2bb222c",
  "o.a.p.ctenantId": "AMS-ENDPOINT-TEST",
  "o.a.p.csourceRequest": "87f93929-0566-4f6d-a2d9-ad28ee07dd86", // principal uuid
  "o.a.p.cdestinationId": "6b7f04ce-45b2-4e42-b4b7-11069eca2b09",  // app uuid
  "o.a.p.cdestinationUrl": "http://localhost:8090/api/appInstalls/configure"
}

Claims

The key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. Set to "AMS".
sub The subject of the token. Set to user's uuid, an app uuid, or a service uuid.
aud The audience of the token. The App's Token Key.
exp The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. Set to 60 seconds after the JWT was created.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
jti The unique identifier for the JWT token Set to a random UUID.
o.a.p.ctenantId The tenant Id Set to AMS-ENDPOINT-TEST.
o.a.p.csourceRequest The source of the request. Set to user's uuid, an app uuid, or a service uuid.
o.a.p.cdestinationId The destination Id Set to the app's UUID. Found in app details.
o.a.p.cdestinationUrl The destination URL The destination URL is the app's URL endpoint being tested.

Headers

"X-OMC-RequestId": "6b7f04ce-45b2-4e42-b4b7-11069eca2b09",  // app uuid
"Content-Type": "application/x-www-form-urlencoded"

Timeout

Each AMS request will timeout in 1 second. Since there are 5 calls in total, it will take 5 seconds if all endpoints timeout.

Response details

The app's expected response is outlined below.

Return code

Any 200 level return code should be used.

Headers

"Allow": supported calls (ie. POST, OPTIONS)

Sample Implementation

OPTIONS Request method

For apps to fully support this feature, apps must support OPTIONS requests. Even if OPTIONS is not fully implemented, this test can still be used to ensure that AMS can reach your application and that the app is up and running. If it returns with a 500 with "Connection timeout" or something similar, this may be an indication to ensure that your app is properly hosted in relation to AMS.

@RequestMapping(value = {"/install", "/uninstall", "/configure", "/saveConfigure"} , method = RequestMethod.OPTIONS)
public int options(HttpServletResponse response) {
   response.setHeader("Access-Control-Allow-Methods","POST");
   response.setHeader("Access-Control-Allow-Origin","*");
   response.setHeader("Allow", "POST");
 
   return 200;
}

Troubleshooting

Here are some common troubleshooting tips for when apps are unreachable.

Network is unreachable (connect failed)

This error detail may indicate the network the app is hosted on cannot be reached. Verify that the network is reachable.

Connection refused (Connection refused)

This error detail may mean the app is down. Check the app's status to ensure the app is reachable.

Learn more

Managing Apps