Test your app with one or more APIs.
The platform provides the following app testing tools:
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.
For more information on performance monitoring, see How do I monitor app performance?
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:
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.
Examples of test clients you can use to send REST requests include: Google rest-client, RESTClient Firefox Add-on, and soapUI.
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:
Before using Dev Console, you must:
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.
To test your app in Dev Console / Dev Client, you'll need to complete the steps below.
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.
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.
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.
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:
|
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. |