API Testing with Test Client

Test your API in Test Client.

API Platform Version: 8.1 and later

Table of Contents

  1. What is Test Client?
  2. How do I access Test Client?
  3. How do I test my API in Test Client?
  4. How do I test my API with different apps in Test Client?
  5. How do the policies I choose affect the user experience in Test Client?
  6. How does Test Client support APIs that don't allow cross-origin API calls (don't support CORS)?
  7. How can I use the API Supports CORS check box for testing?
  8. My API uses the HTTP Security policy. Can people still test it in Test Client?
  9. Why does Test Client send an HTTP OPTIONS request before the call to the API endpoint?
  10. Troubleshooting in Test Client

What is Test Client?

The platform includes an API testing interface that acts as an easy-to-use test client for any API that is fully integrated, with an API definition in the platform. This test tool allows developers to thoroughly test all capabilities of the API.

It can be used for prototyping, testing, and troubleshooting apps against an API. It includes OAuth support for retrieving the OAuth token in order to process the message.

As an API admin, it's a good idea to try your API out in Test Client before you publish, so you can see what experience app developers will have when trying out your API.

Back to top

How do I access Test Client?

Test Client is available in the context of either an app or an API:

  • For app developers: From the app's Details page, on the left menu bar, choose Test Client.
  • For API Admins: From the API's Details page, on the left menu bar, choose Test Client.
    For Simple Dev theme, you'll need to construct the URL. See below.
To construct the Simple Developer URL for an API Test Client:
  1. Take your Simple Developer platform URL, up to and including the #! in the URL, but delete everything after that.
  2. Get your APIID and APIVersionID. If necessary, you can get these from Default Theme/Hermosa Theme by going to the API's Details page (APIID is shown in the URL) and clicking Edit (APIVersionID is added to the URL).
  3. Construct the URL by adding the following after the portion of the URL that you already have:

    apis/{APIID}/versions/{APIVersionID}/testclient

    For example, the URL might be:

    http://{hostname}/#!apis/9add5c43-d9c8-443c-b13f-5388eaf95df8.acmepaymentscorp/versions/f9c0846f-c4b5-4a42-b759-2f92de62aaa4.acmepaymentscorp/testclient

  4. Paste the URL in the address bar and click Enter to go to the Test Client page for your API in Simple Developer theme. You can now put in sample values to test your API.

Back to top

How do I test my API in Test Client?

To test your API in Test Client, you can access it as an app developer or as an API admin. For instructions, see How do I access Test Client? above.

As an API admin, it's a good idea to test:

  • With a few different operations
  • With different parameters and headers
  • With each of the security mechanisms your API supports
  • With each OAuth version, and grant type, your API supports
  • With each token type your API support.

For general info on the settings available, and where different values are set up, refer to the app developer help, reference section: What are the options in Test Client?

Note: The Site Admin can configure the platform to enable or disable the CORS policy for the purposes of testing APIs against apps in the Test Client testing tool. If you need this, ask the Site Admin. More information about this option is available in the Site Admin documentation: Can Test Client use CORS to send the requests to the API endpoint directly without using the Forward Proxy?

Back to top

How do I test my API with different apps in Test Client?

When you're testing you API in Test Client, you can test it in these contexts:

  • Specific app—In the context of any app that you have visibility of. This includes any apps you might have set up yourself, and any apps that have an existing contract with your API.
  • Anonymous—without specifying any app
  • Custom—by defining values yourself

Below is an example of how this might look:

Test Client, Setup, Apps drop-down

Note: To use all the features of Test Client, you'll need to enable popups on your browser.

Note: Display of the shared secret is governed by the platform's settings for apps. If the shared secret is encrypted, it is not displayed. For more information on how to use Test Client when the shared secret is encrypted, see The app's shared secret is not displayed, or is encrypted. How do I use Test Client?

For general information about viewing the shared secret, see How do I view a shared secret?

To test your app against a specific API, or in an anonymous or custom context
  1. From the app's Details page, on the left menu bar, choose Test Client.
  2. Choose the environment, operation, and any other available settings you want to test (available choices depend on the API setup).
  3. Click the Setup button. The top field, Apps, is a drop-down list and includes all available choices: all the apps you have access to, and also the Anonymous and Custom options (see above). For more information about the fields in this dialog, see Test Client: Authentication Settings (app developer help).
  4. Click the Security button, choose options for the policies associated with the API, and save. For more information about the fields in this dialog, see Test Client: Security Settings (app developer help).
  5. Click Invoke.

Back to top

How do the policies I choose for my API affect the user experience in Test Client?

The policies you choose for your API, in the API setup (Tab 3, Proxy, bottom left) affect the options available to developers when using the Test Client tool to try out your API.

The policies you'll need/want to implement will depend on your specific needs; however, it's a good idea to test out the user experience and make sure everything looks good in Test Client for your users.

Note: The specific list of policies available to you for selection is determined by the System Administrator in Policy Manager. If you have questions or concerns about the policies available, or the options within those policies, contact the Site Admin or System Administrator.

Below are some examples of the policies you might choose and the security options that will be available to your users in Test Client:

Test Client security settings: AtmosphereApplicationSecurityPolicy

The AtmosphereApplicationSecurityPolicy is the basic policy for authentication; most APIs use it. If this policy is assigned, Test Client users have access to some or all of the security options shown below (via the Security button).

The token algorithms appearing on the list below are determined by the policy definition in Policy Manager. If token algorithms are not supported, users see only the Token Location drop-down.

Test Client security settings, page 1

For more information about this policy, see Policy List.

For more information about the policy settings, if you are an authorized Site Admin, see What are the AtmosphereApplicationSecurityPolicy settings and how do they affect Test Client?

Test Client security settings: Jose Security Policy v2

Test Client security settings for Jose Security Policy v2

The table below shows the configuration values in the Security window if the JOSE Security v2 policy is applied to the API.

Field... Values...
Private Headers

A private header is any header other than the registered headers defined by the specification; see Private Header Parameter Names section of RFC 7515.

You can specify one or more private headers; check the box and specify the header name and value. You can also add or delete existing private headers as needed.

Test Client security settings: OAuth policy

If the API supports OAuth, Test Client users will see some or all of the settings shown below (via the Security button).

The specific options displayed for OAuth Version, Grant Type, and Authentication Method are determined by the settings specified for the API (API > Details > from the drop-down on the right, OAuth Details) and by the app (Security button):

  • OAuth Version: Only versions supported by the API are displayed.
  • Grant Type: Only grant types supported by the API are displayed. If the API only supports OAuth 1.0a, the Grant Type drop-down is not displayed at all.
  • Authentication Method: If the app developer uploaded a certificate for the app, via the Security button, the Authentication Method drop-down would include a PKI option.

Test Client security settings for OAuth policy

For more information about this policy, see Policy List.

For more information about the policy settings, if you are an authorized Site Admin, see What are the AtmosphereApplicationSecurityPolicy settings and how do they affect Test Client?

Test Client security settings: SameOriginPolicy

If the endpoint URL is on a host that is not the user interface host, same-origin policy prevents the browser from accepting the response unless the API can send the CORS headers.

Test Client includes the SameOriginPolicy option by default, because Test Client is capable of supporting cross-origin resource sharing (CORS) as well as sending the message via the platform's forward proxy server. The page for this policy is the last page of the Security wizard. Depending on the API setup, it might be the only page.

If the API supports CORS, check the box. Otherwise, leave it cleared, or the request will fail.

In Test Client, when you click Invoke, the request is sent directly from the browser to the API endpoint. If the endpoint supports receiving requests from a different domain, the API supports CORS. If it does not, the call will not be successful, and there will be an error, since the API call is sent from the developer portal to the API endpoint.

If you want your API to support CORS, add the CorsAllowAll policy to the proxy API implementation (API > Details > Edit > CorsAllowAll policy).

Note: In some cases, the Site Admin might have modified the developer portal setup so that the SameOriginPolicy option is set in the background, either enabled or disabled, and doesn't display to users. If you don't see this page, and have questions about CORS support, contact the Site Admin.

Test Client security settings for SameOriginPolicy

Test Client settings: HTTP Security Policy

If the API has the HTTP Security Policy attached, the Test Client user must upload a certificate, in the Authentication Settings, in order to test the API. For details and instructions, see Authentication Settings (app developer help).

Back to top

How does Test Client support APIs that don't allow cross-origin API calls (don't support CORS)?

If an API doesn't support CORS, by default any calls to the API from Test Client, on the developer portal's URL, would be refused.

As a workaround to support testing these APIs in Test Client, Test Client employs a proxy server, which sends the request to the Network Director, so that the domain is the same.

By default, when you're using Test Client, if the sending and receiving domains are different the browser sends a pre-flight request (see Why does Test Client send an HTTP OPTIONS request before the call to the API endpoint? below). Based on the results, if the API doesn't support CORS, Test Client sends the request, with special headers, to the proxy server set up for the purpose. The proxy server forwards the request to the underlying infrastructure (Network Director); the request is relayed to the API and the response returned to Test Client.

Back to top

How can I use the API Supports CORS check box for testing?

Test Client includes a check box in the Security settings API Supports CORS, that you can use to check that your API's CORS support is working properly.

For information on how to access this setting, see Test Client security settings: SameOriginPolicy above.

By default, Test Client sends calls to the target API endpoint via a forward proxy, which then forwards the call to the underlying infrastructure, so that API calls from Test Client don't violate the API's CORS policy.

If you check the API Supports CORS check box, Test Client doesn't route calls via the forward proxy. Instead, API calls are routed directly to the underlying infrastructure.

You can use this to test your API; for example, in a scenario where there is an issue and you want to narrow down where the issue is occurring.

If your API does not support CORS, you could also use this check box to test that CORS limitations are working correctly. If you check the box, and the API does not support CORS, the API call from Test Client will fail.

Back to top

My API uses the HTTP Security policy. Can people still test it in Test Client?

Yes. If an API has the HTTP Security Policy attached, Test Client sends an additional header in the request, the Atmo-Client-Token header, as shown below.

atmo-client-token header added for HTTP Security Policy

This allows app developers to test their apps with APIs that use the HTTP Security policy.

Back to top

Why does Test Client send an HTTP OPTIONS request before the call to the API endpoint?

When you're sending an API call in Test Client, Test Client performs an extra step in the background in order to support testing of APIs even if the API doesn't support CORS (cross-origin resource sharing). Here's what happens:

  1. When the API request is initiated, Test Client sends a preflight request, using the HTTP OPTIONS method, to the proxy endpoint. This request essentially says: will you accept this request, with these headers? The specific headers for this type of message are: Access-Control-Request-Method and Access-Control-Request-Headers.
  2. If the response message indicates that the message will be accepted, Test Client then sends the message, via the browser.

For this reason, you'll sometimes see an HTTP OPTIONS request message in the Trace tab of Test Client.

For more information about how CORS support works, see http://www.w3.org/TR/access-control/#resource-preflight-requests (external link to applicable section of CORS specification).

If you want your API to support CORS, add the CorsAllowAll policy to the API implementation (API > Details > Edit > at bottom left of page, CorsAllowAll policy).

Back to top

Troubleshooting in Test Client

This section provides information on some of the issues you might encounter when testing your API in Test Client.

Specific errors are listed in the table below. However, there are many variables associated with API setup and any of these variable factors might influence the way things work in Test Client. If you find that test calls aren't working when you think they should, here are some of the things you could check:

API setup:

  • Make sure the target URL is correctly defined.
  • Make sure the proxy endpoint is correctly defined.
  • Make sure that if media types are specified they are correct.
  • Check that access is set appropriately: public, private, or registered users; allow anonymous access yes or no for each endpoint you've defined.
  • Make sure each operation is defined correctly.
  • Make sure there are no spaces in the operation definitions, including trailing spaces.
  • Make sure the correct policies are assigned to the API.
  • Does the API have the same endpoint in both Sandbox and Live implementations? If so, Network Director cannot differentiate between the two endpoints with API calls, so you might get unexpected results. You can change the proxy endpoint so that there is a difference between the two environments; for example, append /prod and /sbox in the second field.
  • Remember that if the API uses the out-of-box AtmosphereApplicationSecurityPolicy, security is disabled by default, so the Shared Secret value is not validated.
  • Remember that if the API allows anonymous access, neither the App ID nor the Shared Secret is validated.
  • The API might be set up so that anonymous access is allowed with some scopes, but that if the developer provides the App ID additional licenses become available. In this scenario, some capabilities are available with anonymous access, and additional capabilities are available by sending the App ID and Shared Secret.

OAuth setup:

  • If the API uses OAuth, make sure the OAuth policy is assigned (API setup, Tab 3, at the bottom).
  • Make sure the OAuth options are correctly set up (API Details > OAuth Options).

App setup:

Make sure the app has a contract with the API in the environment you're testing.

Policy setup:

If you want to support different security options for OAuth, such as SHA1, SHA 256, or HMAC, you'll need to make sure the AtmosphereApplicationSecurityPolicy supports those options (in Policy Manager). By default, it does not. If needed, coordinate with an Administrator with regard to the settings for this policy.

Error message or scenario Possible reason
400 Bad Request

Any discrepancy between the actual API definition and the API definition in the platform or the values provided in Test Client might cause this error. For example:

  • Extra space in the operation definition
  • Invalid Accept or Content-Type header

You will also see this error if you didn't specify an app, or specified Anonymous, when the API doesn't support anonymous access.

Authorization Failed

The app doesn't have a contract with your API, and the API is not available for anonymous users (therefore valid authorization is required which the app doesn't have).

The API uses the OAuth policy and you changed some of the values without generating a new token.

Binding failure The media type specified for the Accept header isn't supported by the operation. For example, the operation returns application/json only, but the Accept header field specifies a media type of application/xml.
Missing domain. The service may not have been assigned a provider. The API definition includes the OAuthSecurity policy, but the API's OAuth setup was not complete (API > Details > from the drop-down on the right, OAuth Details).
TokenKey does not have Policy Type (OAuth 1.0a or OAuth 2.0) The API definition includes the OAuthSecurity policy, but you didn't click the Security button, choose OAuth settings, and generate the token.
API definition allows anonymous access, but the API call fails if Anonymous is specified for the app. The API has a security policy assigned: either the AtmosphereApplicationSecurityPolicy policy or the OAuthSecurity policy. Both these policies require credentials; so even if you specified that the API allows anonymous access, the security policies will reject anonymous calls to the API.
1010714-Invalid consumer key. The value [APIRuntimeID] in the oauth_consumer_key field is invalid or missing. An invalid value was provided for oauth_consumer_key.

Back to top