API Testing with Test Client
Test your API in Test Client.
Table of Contents
- What is Test Client?
- How do I access Test Client?
- How do I test my API in Test Client?
- How do I test my API with different apps in Test Client?
- How do the policies I choose affect the user experience in Test Client?
- Why does Test Client send an Options request before the call to the API endpoint?
- 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.
How do I access Test Client?
Test Client is available in two places, one for app developers and one for API admins:
- For app developers: From the App Details page, choose Test Client.
- For API Admins: From the API Details page, 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:
- Take your Simple Developer platform URL, up to and including the #! in the URL, but delete everything after that.
- Get your APIID and APIVersionID. If necessary, you can get these from Default Theme by going to the API Details page (APIID is shown in the URL) and clicking Edit (APIVersionID is added to the URL).
- 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
- 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.
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?
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:
To test your app against a specific API, or in an anonymous or custom context
- From the App Details page, on the left menubar, choose Test Client.
- Choose the environment, operation, and any other available settings you want to test (available choices depend on the API setup).
- Click the Security 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 overlay, see Test Client: Config Settings (app developer help).
- Click the Config button, choose options, and save.
- Click Run.
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.
AtmosphereApplicationSecurityPolicy
This 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 Config 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.
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?
OAuth Policy
If the API supports OAuth, Test Client users will see some or all of the settings shown below (via the Config button).
The specific options displayed for OAuth Version, Grant Type, and Authentication Method are determined by the settings specified in the API's OAuth Options overlay (API Details > OAuth Options) 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.
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?
Same Origin Policy
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 proxy server. The page for this policy is the last page of the Security Settings wizard.
If the API supports CORS, check the box. Otherwise, leave it cleared, or the request will fail.
In Test Console, when you click Run, 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.
Why does Test Client send an Options request before the call to the API endpoint?
If your API is set up to support CORS, Test Client performs an extra step in the background in order to provide CORS support. Here's what happens:
- When the API request is initiated, Test Client sends a preflight request, also called an options request, 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.
- If the response message indicates that the message will be accepted, Test Client then sends the message, via the browser.
For this reason, if your API includes CORS support, you'll see an 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 proxy API implementation (API > Details > Edit > at bottom left of page, CorsAllowAll policy).
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 production environments? 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:
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 page > OAuth Details button). |
| 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 Config 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. |