Test Your App

Test your app with one or more APIs.

Table of Contents

1. What app testing tools does the platform provide?
2. How do I test my app in the sandbox?
3. What are some sample REST clients I can use to test an API I want to use?
4. What is the Developer Console (Dev Console)?
5. How do I test my app in Dev Console?
6. How can I make sure I always see the latest results in Dev Console?
7. How do I test authorization of my app with OAuth using Dev Console?

What app testing tools does the platform provide?

The platform provides the following app testing tools:

• Dev Console
• Performance monitoring

Dev Console

The Developer Console (Dev Console) is a web-based REST client that allows you to test different APIs in the context of an application. It is accessible on the Apps > Dev Console page of all apps you add to the platform.

Performance Monitoring

The My Apps > Monitor section includes reporting tools for monitoring the performance of your app. Based on real-time data reported through the monitoring tools, you can troubleshoot potential problems with your app.

• The Charts reporting tool allows you to monitor and view service response time, adherence to defined contract terms (such as, Quality of Service policies), and transaction faults.
• The Usage Logs reporting tool allows you to query and view information about request and response message data for API, App, and Contract activity.

For more information on performance monitoring, see How do I monitor app performance?

Back to top

How do I test my app in the sandbox?

When you submit an API access request for an API's sandbox environment, and your request is approved, you can test your app using the sandbox endpoint.

In many cases, though not all, access to the Sandbox endpoint is granted automatically, so you don't have to wait for approval. If you're not sure whether the contract is approved yet, go to your App Details page and, on the left, click APIs. You'll see the status of your contract, most likely either Pending or Approved.

Once you have access to the sandbox endpoint, you can test your app with the API. For example, you might want to:

• Test the behavior of your app with API calls to verify that the app is behaving as expected.
• Test with simulated transactions and data.
• Check that the flow of information to the app is predictable (i.e., the expected information in the expected format).
• Check that the app is processing the API results correctly.
• Test error handling and usability.

By using a testing environment, you can experiment with different scenarios and make adjustments as needed to make sure that your app works as expected with the API.

Back to top

What are some sample REST clients I can use to test an API I want to use?

Examples of test clients you can use to send REST requests include: Google rest-client, RESTClient Firefox Add-on, and soapUI.

Back to top

What is the Developer Console (Dev Console)?

The Developer Console (Dev Console) is a web-based REST client that allows you to test different APIs in the context of an application. You can use it to try out any API that your app has a contract with. It is accessible on the Apps > Dev Console page of all apps you add to the platform.

Most or all APIs on the platform have an "API Consumer Application Security Policy" assigned. This policy is used to identify (authenticate) the app that is attempting to access the API, to make sure the app is authorized. This policy type supports multiple mechanisms for the app to present its identity, including plain text App Id, signed header with x.509 or a shared secret, or OAuth (1.0a or 2.0). This is the default policy assigned to all APIs. Specific APIs might have other security policies assigned. The policies assigned to the API you're using will affect the settings and options you'll see in Dev Console / Test Client.

When your application is connected to an API (through the API Access Request process), the application security credentials you've assigned to your app (via App Details > Security Credentials) work in conjunction with the API security policies. The request message that is sent to the API must obey the security policies assigned to the API or the request will be rejected.

Note: If your app's contract with an API includes one or more licenses, the Dev Console will only display the operations that the app has permission to access based on the license governing the contract.

You can use Dev Console / Test Client to:

1. Determine what is needed to send a request to an API.
2. Verify if you can successfully send a request to an API.
3. If your API calls are failing in the sandbox or production environment, test to see if you get different results in Dev Console.
   
   For example, if your app sends a request message to the API and it is rejected, it might be because the security credentials in your app do not match those configured in the API policy. Let's say your app is configured with an SHA1 - Shared Secret, but the API Policy is configured with SHA with RSA - PKI. In this case, the credential mismatch would cause the request to fail. You could test with different credentials using Dev Console.
4. Test different operations in your app.

Before using Dev Console, you must:

1. Identity an API you would like to test with your app. This API can be one that is already available in the platform, or can be one that you've added using the Add a New API function via the Plus Menu.
2. Add an app to the platform. This can be done using the Add a New App function via the Plus Menu. Make sure that you've assigned the desired security credentials in the App Details > Security Credentials section.
3. Submit an API Access Request (via the Access link on the API Details page) for the API you want to try out. The API Access Request must be approved by the API Admin before you can begin testing the API with the Dev Console. In many cases, a contract in the Sandbox environment might be automatically approved, but production access requests generally require manual approval. The approval process might be different for different APIs.

The Dev Console includes an API drop-down that displays a list of the APIs that your app is currently connected to. When you select an API from the drop-down, the platform analyzes the API configuration and the security policies assigned to the API and populates the fields with the appropriate information. After the Dev Console is populated, you configure each test case and then click Run It.

The following illustration shows the Dev Console with the Bing VirtualEarth API loaded. Continue to How do I test my app in the Dev Console? for an example walkthrough that illustrates how to test your app with the Dev Console.

Back to top

How do I test my app in Dev Console?

To test your app in Dev Console / Dev Client, you'll need to complete the steps below.

To test an app in Dev Console / Test Client:

1. Set up an app in the developer platform. For instructions, see How do I create a new app?
2. Set up a contract between your app and the API you want to test. For instructions, see How do I get API access for my app?
3. Go to Dev Console / Test Client and choose the API/environment you want to test.
4. Choose the operation you want to try out.
5. Specify additional values needed for the specific operation, such as headers and parameters. Dev Console will offer you the choices that are valid for the specific API and operation that you've chosen.
6. Check the URL to make sure it looks right.
7. Set up additional security values as needed. The requirements will vary depending on the security mechanisms supported by the API and used by your app. If the API uses OAuth you'll need to authenticate and get a token.
8. Click Run It (Dev Console) or Run (Test Client).

Back to top

How can I make sure I always see the latest results in Dev Console?

If the API you're using sets the cache-control response header, the response message is cached. When you send multiple requests, the first response is cached for the time specified as the value in the API's cache-control response header, and you may see the same response for all subsequent requests until the cache expires. This could mean that when you send a subsequent request, the response you see is from the cache, not from the server. If this happens, there will only be one transaction log, even if you click the Run button multiple times, until the cache expires or is cleared.

To make sure you are always seeing the latest information, clear your browser cache before sending subsequent requests.

Back to top

How do I test authorization of my app with OAuth using Dev Console?

The following procedure provides a simple example of how to use the Dev Console to test authorizing your app with OAuth and then sending a request.

Pre-conditions

1. Your app must be connected to the API. See How do I get API access for my app?
2. The API must support OAuth.
3. The app security credentials must be a type of credentials that the API supports.

Note: For app security, OAuth supports shared secret or PKI options. If you want to use the PKI option instead of shared secret as credentials, Dev Console needs your app's private key. To provide the private key, you can upload the keystore, which is a file format that supports both private key and certificate. Dev Console supports the PKCS12 keystore format. If you are uploading a keystore, make sure it matches this format.

Procedure

1. Go to the App Details page.
2. On the left menu, choose Dev Console (in Simple Developer theme, choose Test Client).
3. Select the API. Based on the API details, the following occurs:
   • The details of the API (Endpoint, Operation, Method, Accept header, Content-Type header, Path, and URL) are displayed
   • The Security button is enabled so that you can set up the app security.
4. Choose an operation you want to invoke, and specify additional values such as headers and parameters. For more information on these fields, see Test Client: Configuration Values.
5. Set up the security settings. Depending on the specific scenario, you might need to set up one or more of the following:
• Credentials: App ID and Shared Secret, or upload a keystore file that includes your app's private key and certificate (PKCS12 keystore). If you upload a keystore file you'll also need to provide the password for the file.
• For AtmosphereApplicationSecurityPolicy: Authentication method, Token Algorithm and Token Location. This sets values for generating the security token to be sent to the API endpoint, and determines how it is sent.
• For OAuth Security Policy: OAuth Version, Grant Type, and Authentication Method. Then click Get Token to generate the token.
6. To send a test request to the API, click Run It. The results are shown in the Dev Console window, and the transaction is recorded in the transaction log for the app and for the API (viewable via App > Monitor).

Test Client: Configuration Values

The table below shows the configuration values in the Test Client main window.

Field...	Values...
API	Choose an API you want to test against. If the API you want isn't on the list, your app doesn't yet have an approved contract with the API. To check the status of app/API contracts, go to App > APIs.
Operation	Choose an operation you want to test against. If your app's contract with the API is governed by a license, you'll only see the operations you have permission to use.
Method	The HTTP method that applies to the operation you selected is displayed.
Endpoint	The list of endpoints you have access to, for the API you selected. If there are no URLs or a URL is missing, you have probably not been granted access to this endpoint yet. Check your API access requests to see if there is a pending request.
Path	The path includes all the query and path parameters in parentheses (for example {}). Each parameter can be filled out to make up the path dynamically.
Headers: Content-Type	The Content-Type header sent in the request. This lets the API know the format of the information you are sending. To specify a custom media type, or a media type that isn't listed, select Other. If the operation is a GET, Content-Type is not applicable and is grayed out.
Headers: Accept	The Accept header is used by the App to tell the API what content types it will accept. To specify a custom media type, or a media type that isn't listed, select Other.
Headers: Add Header	Use this field to add one or more custom headers. Just click Add and specify the header name and value.
Parameters:	The list of parameters that will be sent to the API. There are three types: path, query, and form: Path parameters are determined by the path for the operation; you can't add or remove them. Query parameters may be described in the path, but you can also add your own. Form parameters can only be added when the method is POST/PUT and the Content-Type is application/x-www-form-urlencoded.
URL	The URL that the test message will be sent to. The URL that's displayed is generated based on the information entered in earlier fields.
Credentials	Click to set up your app's credentials. Values required vary according to the API setup. For details, see below.
Security Settings	Click to set up your app's security settings. Values required vary according to the API setup. For details, see below.
Request/Response	When you click Run, the request and response are displayed. Use this information to test and debug as needed. You can also click the tabs to see the request and response in different formats: Raw, Pretty, and Headers.

The table below shows the configuration values in the Test Client Credentials window (in Dev Console this is in Security).

Field...	Values...
App ID	The unique ID that identifies your app to the API, that will be used for the request. If it is blank, you will need to go to the API provider directly and read their instructions for getting an App ID.
Shared Secret	The unique shared secret value that validates your app with the API, that will be used for the request. If it is blank, you'll need to enter your app's shared secret value. If you don't have a shared secret on the platform, go to the API provider directly and get a Shared Secret value for your app.
Upload Keystore	Check this box to upload a keystore file.
File to Upload	Browse to the location of the PKCS12 keystore file that contains the private key and certificate of the App.
Password	The password for the keystore file, assigned when the keystore file was created.

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

Field...	Values...
OAuth Version	Choose from OAuth versions supported by the API.
Grant Type	OAuth 2.0 defines four grant types (security scenarios, or use cases). Choose from the list of grant types supported by the API. For more information, refer to the spec: http://oauth.net/2/.
Authentication Method	Choose from authentication methods supported by the API.
Get Token button	Click to get an access token from the API’s identity provider, so your app can access the API. Test Client will add the access token to each request. You might need to log in to the identity provider.
Renew Token button	If the token has expired, click to get a renew token from the API’s identity provider, so your app can access the API. You might need to log in to the identity provider.

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

Field...	Values...
Token Algorithm	The algorithm to be used for generating the security token to be sent to the API endpoint.
Token Location	Indicates how the token is added to the message: Header, QueryString, Form, or Cookie. The Form parameter is only applicable for POST or PUT.

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

Field...	Values...
SameOriginPolicy: API Supports CORS	If the endpoint URL is on a host that is not the user interface host, same-origin policy will prevent the browser from accepting the response unless the API can send the CORS headers. Check this box if the API supports CORS. If it doesn't, clear the box and the request will be proxied.
Authorization Endpoint Extension Parameters	If your OAuth provider requires any additional parameters to be sent to the authorization endpoint, beyond the OAuth specification, enter the parameter names here. Dev Console will show these parameters to collect the values from developers.

Back to top