23 REST Connector APIs

Oracle Mobile Cloud Service (MCS) enables you to create REST connector APIs to connect to external REST services. As a service developer, you can create connector APIs to make it easier to call these services from the implementations of your custom APIs.

The key steps to creating a connector are generally to establish a connection to an external service by defining endpoints that consist of a set of operations that act on their associated resources. In Oracle Mobile Cloud Service (MCS), this connector is an API that’s modeled in a rich graphical user interface. At runtime, these connectors are called as APIs.

What Is a REST Connector API?

A connector is a means of enabling a mobile backend to communicate with an external service such as enterprise system or third-party APIs, which in turn, allows a mobile app to interact with the functions of that service. A connector API is a configuration for communicating with a specific external service to send and receive data.

Specifically how the service is accessed and how the data is transmitted is dependent on the type of the connector protocol that you use. REST connector APIs give you a standard way to connect a mobile app to existing REST services and at the same time benefit from the Oracle Mobile Cloud Service's built-in security, diagnostics, and analytics features.

The connector communicates and passes information between the client and the server using the HTTPS protocol. The information passed can be in the form of XML or JSON (Javascript Object Notation). REST doesn’t contain a messaging layer. It uses a set of rules to create a stateless service.

The REST Connector API wizard walks you through creating REST Connector APIs, from specifying a remote service and setting security policies to testing your endpoints. Additionally, the wizard supports Swagger. When you provide a Swagger descriptor URL, the wizard introspects the endpoints available from that file. The available resources are identified and displayed. You simply select the resources of the external service.

Note:

Currently, Swagger is supported only in the JSON format.

Note:

Only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port.

REST Connector API Flow

Here’s how the design-time flow for a REST Connector API goes:

  1. A REST Connector API is created with the REST Connector API wizard in Oracle Mobile Cloud Service.

  2. If a Swagger 2.0 descriptor URL is provided, design time credentials are passed and a connection to the descriptor is made. The design time credentials are saved in the Credentials Store Framework (CFS) in MCS.

    If a remote service URL is provided, a connection is to the external service is made.

  3. After the credentials are authenticated, MCS downloads and parses the descriptor and retrieves the metadata.

    Note:

    Currently only Swagger in JSON format is supported. Swagger metadata in yaml format can’t be parsed.
  4. Optionally, rules are set after the desired resources are selected or after a connection to the external service is made, in the case where a remote service URL was provided.

  5. If a descriptor has been provided, the resources are displayed and the desired resources to access from the custom code are selected.

    No resources are displayed if a remote service URL was provided.

  6. The Oracle Web Services Manager (Oracle WSM) security policy to be used at runtime is configured.

  7. The configuration is saved. The endpoints for the selected resources are listed on the Test page and tested. Mobile user credentials are provided to test the connector API.

After you’ve created a connector API, you can select it from a list of connectors. Just because the connector is created doesn’t mean it can be called from the implementation code of a custom API. You’ll need to complete the connector configuration and test the endpoints first.

Here’s how the runtime flow goes:

  1. Custom code sends a request to the REST Connector API.

  2. The connector API retrieves the remote URL or, if a descriptor URL was provided, the connector implementation checks whether or not the resource is enabled. If the connector receives a request to a path or resource that isn’t enabled by the user, a 404 error is returned and the request isn’t sent to the external service.

    The security policy and any rules are applied. The JSON payload is passed through untouched.

  3. The connector sends the request to the external service.

  4. The service sends a JSON response back to the connector.

  5. The connector sends the JSON response to the custom code.

Why Do I Want to Use a REST Connector API?

Using Oracle Mobile Cloud Service connectors gives you advantages over making direct calls to external services.

Using a REST Connector API provides you with the following benefits:

  • Allows for simplified declarative connection and policy configuration.

  • With a Swagger descriptor, determines the available resources and creates endpoints for you.

  • Allows calls to an external service, along with security policy setup and credentials, to be encapsulated and used consistently across the mobile API.

  • Provides you with extensive diagnostic information as its tightly integrated with the Oracle Mobile Cloud Service diagnostics framework. Any outbound REST calls made through connector APIs are logged, which greatly helps with debugging.

  • Allows for tracking and analytics on remote API usage.

  • Lets you define interaction with the service at design time when you test the validity of your endpoints so that the terms of that interaction aren’t dependent on user input at runtime. This protects both the end system and your mobile backend from harm.

  • Provides a consistent design approach among multiple connector types for interacting with external services.

  • With any change in the interface for a service, lets you can handle any necessary updates, testing, and migration in one place.

Why Use Oracle Mobile Cloud Service Connectors Instead of Direct JavaScript Calls to External Resources?

Although you’re not required to use Oracle Mobile Cloud Service connectors to connect to external services, using these connectors provides security advantages and other benefits that come with Oracle Mobile Cloud Service.

When you set up an Oracle Mobile Cloud Service connector, you preconfigure security policies required to connect to the target service. If you use a REST Connector API to define how external REST services are called, then you can carefully define which endpoints can be called by the mobile app and track their usage. For example, with a REST Connector API, you can configure user credential and account information for a remote service in a single place. To get usage information, see Getting the Test Results.

How Do I Create a REST Connector API?

Use the REST Connector API wizard to quickly configure your connector API by providing a name and description, specifying timeout settings, adding rules, setting a security policy, and testing it.

Creating a connection to an existing REST service can be a simple two-step operation:

  1. Name your connector API.

  2. Provide the URL to the external service.

You have the option of applying rules to form specific requests or responses for the data that you want to access. In addition, you have the ability to configure client-side security policies for the service that you’re accessing and test and check the results of your connection.

As soon as it’s created, your connector API is listed on the Connectors page. When at least one connector API exists, you’ll be taken directly to the Connectors page when you click Connectors from the side menu. From the catalog, you can select the connector API and edit it, publish it, create a new version or update an existing version, deploy it if it has a Published state, or move it to the trash. See Connector Lifecycle.

You can call connector APIs from the implementation code of custom APIs. See Calling Connector APIs from Custom Code.

Setting the Basic Information for Your REST Connector API

Before you begin configuring your connector, you must provide some initial basic information like the connector API name, the address to the remote service, a brief description, and a local URI (from which the connector API will be available to the custom code):

  1. Make sure that you’re in the environment for which you want to create the REST Connector API.

  2. Click open the side menu icon and select Applications > Connectors from the side menu.

    The Connectors page appears. If no connector APIs have been created yet, you'll see a REST Connector icon and a SOAP Connector icon. If at least one connector API exists, you'll see the a list of all the connector APIs. You can filter the list to see only the connector APIs that you're interested in or click Sort to reorder the list.

  3. Click REST (if this is the first connector API to be created) or New Connector and from the drop-down list, select REST.

    The New REST Connector API dialog appears.
  4. Identify your new REST Connector API by providing the following:

    1. API Display Name: Enter a descriptive name (an API with an easy-to-read name that clearly identifies the API makes it much easier to locate in the list of connector APIs).

      For example, myMapAPI.

      Note:

      The names you give to a connector API (the value you enter in the API name field) must be unique among connector APIs.

      For new connectors, a default version of 1.0 is automatically applied when you save the configuration.

    2. API Name: Enter a unique name for your connector API. The default value is a simplified form of the value that you entered for the API Display Name.

      For example, mymapapi.

      By default, this name is appended to the relative base URI as the resource name for the connector API. You can see the base URI below the API Name field.

      Note:

      The connector API name must consist only of alphanumeric characters. It can’t include special characters, wildcards, slashes /, or braces {}.

      If you edit the name for the API here, the base URI is automatically updated.

      Other than a new version of this connector API, no other connector API can have the same resource name.

    3. Short Description: Provide a brief description, including the purpose of this API.

      This is the description of the API that will be displayed on the Connectors page when this API is selected.

    After you've filled in all the required fields, click Create, to display the General page of the REST Connector API dialog.

    • HTTP Read Timeout: The maximum time (in milliseconds) that can be spent on waiting to read the data. If you don’t provide a value, the default value of 20 seconds is applied.

    • HTTP Connection Timeout: The time (in milliseconds) spent connecting to the remote URL. A value of 0mms means an infinite timeout is permitted.

      The HTTP timeout values must be less than the Network_HttpRequestTimeout environment policy, which has a default value of 40,000 ms. To learn more about environment policies, see Environment Policies.

      Note:

      If you have a mobile cloud administrator role in addition to your service developer role, you can open the policies.properties file to see the value for the network policies for the current environment from the Administrator view. Otherwise, ask your mobile cloud administrator for the values.
  5. Click Save to save your current settings.

    If you want to stop and come back later to finish the configuration, click Save and Close. You can always return to edit your configuration when it's in a Draft state. You can always click Cancel at the top of the General, Rules, and Security wizard pages to cancel that particular configuration operation.

  6. Click Next (>) to go to the next step in configuring your connector API.

    After the basic information is provided, you can specify the interaction details for your connector API.

The Rules and Security steps to creating your REST Connector API are optional. If you provide a descriptor on the Descriptor page, you’ll be able to navigate to the Resources page where you can select the methods for the exposed resources. However, if you choose to provide a remote service URL instead on the Descriptor page, the Resources page isn’t displayed in the navigation bar. You’ll be still be able to set Rules if you want and the runtime security policy, though.

To be sure your connector API configuration is valid, you should test it thoroughly (not just from the Connector API Test page) before publishing it. That is, you should also test the custom API (with its implementation) that uses this connector API. See Testing and Debugging Custom Code. Essentially, if you’re ready to publish the connector API, you should also be ready to publish the custom API that calls it.

If you’ve already published the connector API and then find that you need to change it, you must create a new version of it. See Creating a New Version of a Connector.

Providing the Descriptor

If you provide a Swagger descriptor URL, the REST Connector API wizard can examine the descriptive metadata and obtain resources and fields from it.

Note:

Only Swagger metadata in JSON format is currently supported.
If you don’t have a descriptor, simply select that option and enter the remote URL of the external service.
  1. On the Descriptor page, select the means by which the REST Connector wizard reads the Swagger metadata:
    • Web Address. Select this option to enter the URL of the Swagger metadata.

      Click Oracle Cloud Service REST API Catalog to get a descriptor from the Oracle Cloud Service REST API catalog. Copy the address for the descriptor you want to the clipboard and paste it into the Location field.

    • I don’t have a descriptor. Select this option to enter the URL of the external REST service.

      The remote URL is the address of the resource for the external service that this connector API calls.

      You can save time by verifying that the URL you’re providing is trusted at trustedsource.org, otherwise, even if your connector API is configured correctly, the connection will fail. See Common Custom Code Errors.

      The HTTPS protocol is used most often, but you can use HTTP if the web service is on a nonsecure site.

      Note:

      When specifying a port, only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port.
      You can optionally enter query parameters in the URL, for example:
      https://maps.googleapis.com/maps/api/directions
      https://maps.googleapis.com/maps/api/directions/json
      https://maps.googleapis.com/maps/api/directions/location?origin=Pasadena

      Typically, you set parameters in rules instead of in the Remote URL field, but both ways are possible. See Setting Query Parameters in Remote URLs. To learn more about setting rules, see Setting Rules.

  2. If your provided a descriptor URL, enter your basic authentication credentials (user name and password) to access the descriptor if you selected the Web Address option. Then you can proceed to the Resources page.

    If you provided a remote URL, your next step is to set rules (optional) or select a security policy.

    Note:

    If need to edit your configuration, the descriptor URL and design time credentials you provided are preserved. However, if you provide a different descriptor URL, you will need to enter the credentials to access that descriptor instance.
  3. Click Next to proceed.

Setting Rules

You set rules to define the interactions between your mobile app and a service. Rules provide a way for you to add default parameter values for all calls to resources on the service, calls to a specific proxy path, and calls for certain types of operations (verbs). This helps enforce consistent syntax of the URL string, saves the custom code developer from having to insert these values, and makes it possible to track the different calls through analytics.

You can skip this step and proceed to Security if you don't want to set any rules. If no rules are applied, all calls are passed through the proxy to the existing service.

You can create one or more rules. Each rule can have one or more parameters of type Query and Header.

  1. Click New Rule.

    A rule construct displays where you can select the parameter type, name and value for the rule.

  2. Click Add Parameter and select a Query or Header parameter type and enter the query or header name, and its value. You must have at least one parameter for the rule to be valid.

    Note:

    Although you can define rules to set certain headers by default, the rules aren’t applied if the client that called the connector directly through custom code or indirectly, such as from a web browser or mobile app, has already set the same headers.

    In particular, setting the format of the request body is usually done in the custom code with the Content-Type header, not as a REST Connector rule. Similarly, setting the format of the response body is also done in the custom code with the Accept header, not as a REST Connector rule.

    You can add as many parameters to a rule as you want but it's better not to overload a rule with too many operations. A simpler rule construct is easier to troubleshoot.

  3. Expand Resources and edit the remote URL to provide a resource for the rule to be applied to. The base URL value is what you entered in the setting basic information step and it can’t be edited.
  4. Select Do not apply to lower level resources if you want the rules applied only to the resource level specified in the Remote URL.
  5. (Optional) Unselect the HTTP methods that you don’t want applied to rules that you just defined. By default, all methods are selected. You can have more than one method:
    • GET: Performs a read operation

    • PUT: Performs an update (or store) operation

    • POST: Performs a create operation

    • DELETE: Performs a delete operation

    • HEAD: Reads the HTTP metadata

    • OPTIONS: Requests information, such as the options or requirements of the resource

  6. (Optional) Click New Rule to create another rule.

    Note:

    If you define a rule that conflicts with another rule, the first rule applied takes precedence and the conflicting rule is ignored.

    When you're done, click Save and then Next (>) to go to the next step in configuring your connector API.

    To delete a rule, click X in the Rule banner.

The description of the rule that you just defined is shown in the Rule banner just above the Default Parameters section. For example, let's say the following values have been provided:

  • Remote URL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

  • Local URI = myMapAPI

  • Rule with the following parameter: Query:key:A3FAEAJ903022

  • GET and PUT HTTP methods

The rule description would read as follows:

For GET to https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle available at myMapAPI/directions, Include Query:key=A3FAEAJ903022.

If no rules were created, the description would simply read:

For ALL METHODS to https://maps.googleapis.com/maps/api/directions available at myMapAPI, No default parameters will be applied.

Now you have a base URI that maps to the existing service. Using our example:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle maps to https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Selecting Endpoints

If you provided a descriptor, you’ll have access to the Resources page. Here’s where you’ll be able to examine details about the resources that are included in your connector configuration and select the endpoints that you want in your connector configuration.
  1. Review the runtime base URI of the external REST service.

    This is the address of the runtime server that you’re executing against. It consists of the runtime server port and the base path of the Swagger descriptor. For example, if /documents/api/1.1 is the base path, then the URI would look like:

    http://server.port/documents/api/1.1

    Note:

    This URI is extracted from the metadata if present. If the metadata doesn’t contain the address, you must provide it or you won’t be able to proceed to the next step in the connector configuration.
  2. Select an endpoint to add it to your configuration.

    Resources methods aren’t selected by default. If you want a particular endpoint, select it. Un-selecting the resource, un-selects all of its methods.

    When a method is selected, you can view its details, including its associated methods. The Details panel displays the following information for the selected resource:
    • Description. The text content of the Swagger description value for the method.

    • Parameters. A list of the required and optional parameters to use when calling the method.

    • Responses. A list of the available responses that are returned when calling the method.

    Use the Filter field to locate a resource based on its name or description.

    Click Select All to select all the resources. To start over, click Clear All.

    Click Expand All to display all the associated methods for every resource.

  3. Click Next to set the runtime security policy.

Setting Security Policies and Overriding Properties for REST Connector APIs

Before you create your connector API, you should consider how to handle its security. You have the option to configure a secure a connection to an external service by setting security policies or authorization headers. Selecting a security policy that describes the authentication scheme of the service to which you’re connecting to is the recommended way to set security. See Security and REST Connector APIs to find out how to configure a secure connection with headers.

Every security policy has properties, called overrides, which you can configure. One reason to override a policy configuration property is to limit the number of policies that you have to maintain: rather than creating multiple policies with slightly varied configurations, you can use the same generic policy and override specific values to meet your requirements.

To select a security policy and set the policy overrides:

  1. In the REST Connector API wizard, click the Security navigation link.
  2. Select the security policy from the list of available policies and click the right arrow to move it to the Selected Policies list.
    Select only a single policy for your connector API. A description of a selected policy is displayed below the list. To find out more about the supported security policy types for the REST Connector API, see Security Policy Types for REST Connector APIs.
  3. Specify overrides, if applicable, to the selected policy if you don't want to use the default values.
    To override a property, enter or select a value other than the default. For a description of policy properties, see Security Policy Properties.

    To set a Credential Store Framework (CSF) Key value, see Setting a CSF Key. To learn about credential keys and certificates, see CSF Keys and Web Service Certificates.

  4. Click Save to save your work or Save and Close to save your work and exit the REST Connector API wizard.
  5. Click Next (>) to go to the next step, testing the connector.
Setting a CSF Key

If you want to authenticate the user, you must set the csf-key property. You must set the csf-key property if you’ve selected http_basic_auth_over_ssl_client_policy, http_samle20_token_bearer_client_policy, or http_samle20_token_bearer__over_ssl_client_policy.

Note:

If you set the csf-key and the security policy has a subject.precedence property, that property should be set to false. If you need to set subject.precedence to true, you must also set the propagate.identity.context property. In the latter case, don’t set csf-key.

Click Keys open the Select or Create a New API Key dialog icon in the csf-key field in the Security Overrides section to open the Select or Create a New API Key dialog.

Provide a CSF Key in one of the following ways:

  • Select an existing key from the Available Keys list (a description of the selected key is displayed below the list). The list displays only the keys supported by the given policy property.

    When you select the key, its name appears in the Key Name field. Click Select to add the key. The other fields in the CSF Key Details pane are used only when creating a key.

  • Create a new basic (CSF) credentials key.

To create a new CSF key:

  1. Click New Key.
  2. Enter a key name that is descriptive and easy-to-read. Note that after you create the key, you can’t change the key name.
  3. Enter a brief description of the key's purpose.
  4. Enter the user name and password (the user credentials) for the service to which you are connecting.

    Repeat the password in the confirmation field.

  5. Click Save to add the key to the Available Keys list.
    You can create another key by clicking New Key or edit an existing one. Save toggles to Select allowing you to select a key in the list. Click Cancel to quit the task..
    The key name value will appear as the override value on the Security page. Note that the value of the key that you create pertains only to the environment in which it’s set.
If you want to edit some aspect of an existing CSF key, select it from the Available Keys list and modify the fields as needed. To learn more about CSF keys, see CSF Keys and Web Service Certificates.

Testing the REST Connector API

Now that you've defined your REST Connector API and saved the configuration, you'll want to verify that you’re able to actually send a request and receive the expected results from the web service. Testing a connection is also an optional step but can save you time by identifying and fixing problems now before you finalize the connector API. The Test page lets you test one endpoint at a time.

If you provided a descriptor, you have two testing modes to choose from:

  • Standard testing

    If you provided descriptor metadata, the standard testing mode is displayed in which the request and response bodies are generated from the descriptive metadata and displayed in the Request and Response tabs. All you have to do is select the parameters to test with for GET methods and include any HTTP headers that you want to test with. See Testing in Standard Mode.

  • Advanced testing

    Alternatively, you can refine your testing by selecting Testing in Advanced Mode (the test mode you enter if you provided a remote service URL). Without descriptive metadata, you select the method and resource to test, include any HTTP headers you want to include, and manually create the JSON body. See Testing in Advanced Mode.

Testing in Standard Mode
If you provided descriptor metadata, you’ll automatically get the standard test page, which lists all the available query parameters for you as well any example bodies or schemas for the request and response payloads (if present in the metadata).

To test your connector with the endpoints exposed for you:

  1. Click the Test navigation link.
  2. Select the endpoint you want to test.

    Endpoints are listed on the left side of the page. Enter a partial resource name in the filter field to narrow the list to make it easier to find the endpoint you want. When you select an endpoint, the method, the resource name, and the URI of service is displayed on right side of the page.

  3. Set the default test credentials if you’re in the design phase and just want to see if your endpoints are valid, or if you want to test multiple endpoints during the session.
    Otherwise, skip this step and fill out the fields in the Authentication section for each method you test.
    1. Click Default Test Credentials at the top of the page.
    2. Select a mobile backend to associate the API with and the version of the mobile backend.
    3. If both OAuth and HTTP Basic Authentication are enabled for the mobile backend, select one in the Authentication Method field to use for testing.
    4. Click Save to apply the credentials.
  4. Click Request and expand Parameters.

    When you select a GET method, all the available query parameters are displayed on the Request tab.

    1. For a GET method, enter a parameter value.
    2. (Optional) Click Example to view the example body, if one was provided. For methods other than GET, enter an alternate example to test with by clicking Use Example. The provided example body is copied into the text bod. You edit the example as needed.
    3. (Optional) Click Schema to view the request body schema if one was provided.
  5. Expand HTTP Headers and click Add HTTP Header to add a header.

    Select the header that you want to include for testing purposes and provide a value in the text field.

  6. Expand Authentication, select the mobile backend and its version that are associated with this API, and enter your mobile user credentials. If both OAuth and HTTP Basic Authentication are enabled for the mobile backend, select one in the Authentication Method field to use for testing.
  7. Click Response, expand the status code and click Example or Schema to review the example or schema for the response body, if one was provided.
  8. Click Test Endpoint.

    Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, then click Cancel Test.

    If you want to make changes to the testing parameters, click Reset to clear all the fields.

To be sure your connector API configuration is valid, test it thoroughly (not just from the Connector API Test page) before publishing it. You should also test the custom API (with its implementation) that uses this connector API. Essentially, if you’re ready to publish the connector API, then you should also be ready to publish the custom API that calls it.

If you need to make changes to a connector API that's in the Published state, then create a new version of it. For information on creating a new version, see Creating a New Version of a Connector.

Testing in Advanced Mode

The advanced test page lets you manually set path parameters, add headers, and the request and response payloads. It displays a read-only numbered list of all the rules (and their full descriptions) that you defined. If you didn't set any rules, the first field you'll see on this page is the HTTP Method field.

To manually configure a connector test:

  1. Click the Test navigation link.
  2. If you provided a descriptor, turn Test in Advanced Mode to On.

    The advanced test page displays automatically if you provided a remote service url.

  3. Select the HTTP method that you want to test from the drop-down list.
  4. Specify any resource path parameters in the Local URI field as needed for testing purposes. For example:
    directions/json?origin=los+angeles&destination=seattle

    The field is automatically prefixed with the local URI that you defined when you entered an API name. Following our example, the full contents of the field would look like this:

    myMapAPI /directions/json?origin=los+angeles&destination=seattle

    Notice that if you defined any rules, the Rules Applied field (below the Body field) displays numbers that correspond to the rules that are applicable for the selected operation. The Remote URL field shows the exact string that will be passed to the service for the test.

  5. Add one or more request or response HTTP headers as needed.

    These headers are for testing purposes only and won't be added to your REST Connector API configuration.

  6. Click in the HTTP Body field to create your message body (the payload) in the source editor.
    For example:
    {
      "status":"ZERO_RESULTS",
      "routes":[ ]
    }

    Keep the content of the message body relevant to the purpose of the connector, that is, don’t bloat the message by adding extraneous data. Including only pertinent data in the message body facilitates quick transmission of the request or response.

  7. If the service that you're connecting to requires authentication, open the Authentication section and enter your mobile user credentials for each method you test. If you’re using default test credentials (Step 7), you can skip this step.

    With SAML-based security policies, the identity of the user making the call is propagated to the external service. For other security policies such as HTTP Basic Authentication and username token, the credentials used to authenticate with the external service are provided in the policy overrides as CSF keys. Depending on the operation that you’ve defined, you may have to enter specific credentials for each operation or you might be able to use one set of credentials for all the methods to authenticate your connector with the service.

  8. Click Save as current mobile backend default credentials to save the user name and password that you provide as the default.
  9. If you’re in the design phase of creating your connector and you just want to see if your endpoints are valid, click Default API Designer Test Credentials and select a mobile backend that you’re registered with and its version number.
    Optionally, you can enter your mobile user credentials (user name and password).

    These default test credentials are persistent across all the methods that you test. They remain valid during the current Oracle Mobile Cloud Service session.

  10. Click Test Endpoint.

    Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, click Cancel Test.

    Click Reset to clear the fields and modify the test parameters.

  11. Click Done when you’ve finished testing your endpoints.

Getting the Test Results

Test results are displayed at the bottom of the Test REST API page. The result indicator is the response status:

  • 2xx: indicates a successful connection

  • 3xx: indicates a redirection occurred

  • 4xx: indicates a user error occurred

  • 5xx: indicates a server error occurred

Here's a list of the more common status codes that you'll want to use:

Code Description

200 OK

Successful connection.

201 CREATED

Successful creation through either a PUT or POST operation.

204 NO CONTENT

Successful connection but no response body (used for DELETE and UPDATE operations).

400 BAD REQUEST

General error when fulfilling the request, causing an invalid state, such as missing data or a validation error.

401 UNAUTHORIZED

Error due to missing or invalid authentication token.

403 FORBIDDEN

Error due to user not having authorization or if the resource is unavailable.

404 NOT FOUND

Error due to the resource not being found.

405 METHOD NOT ALLOWED

Error that although the requested URL exists, the HTTP method isn’t applicable.

409 CONFLICT

Error due to potential resource conflict caused, for example, by duplicate entries

500 INTERNAL SERVER ERROR

General error when an exception is thrown on the server side.

Click Request to see the metadata for the transaction, such as header information and the body of the request.

Click Response to see the details of the response returned. The response code tells you whether the connection was successful.

Test each of your operations and modify them as needed to validate your endpoints.

After your connector API is tested, published, and deployed, you can go to the Connectors page to see analytical information about it, such as how often the connector is being called and what apps are using the connector. See Managing a Connector.

Getting Diagnostic Information

You can view the response code and returned data to determine if your endpoints are valid. A response status other than 2xx doesn't necessarily mean the test failed. If the operation was supposed to return a null response, a response should show a 4xx code.

By examining multiple messages, you can more easily determine where issues occur. For every message that you send, MCS tags it with a correlation ID. A correlation ID associates your request with other logging data. The correlation ID includes an Execution Context ID (ECID) that’s unique for each request. With the ECID and the Relationship ID (RID), you can use the log files to correlate messages across Oracle Fusion Middleware components. Click Logs on the Administration page to view logging data. You can also retrieve records from Oracle Fusion Middleware Logging using the call's ECID.

Depending on your MCS access permissions, you or your mobile cloud administrator can view the client and server HTTP error codes for your API's endpoints on the Request History page, allowing you to see the context of the message status when you're trying to trace the cause of an error. Every message sent has a set of attributes such as the time the event occurred, the message ID, the Relationship ID (RID), and the Execution Context ID (ECID).

To obtain and understand diagnostic data, see Diagnostics.

Security and REST Connector APIs

MCS gives you the flexibility to configure a secure connection to external services through the use of security policies or authorization headers.

Here are the different ways that you can configure a REST Connector API to communicate with a secured service:

  • Configure a security policy.

    On the Security tab of the REST Connector UI, decide which policies describe how the external service that you’re communicating with is secured, and configure it as necessary. Configuring a security policy is the recommended practice and takes precedence over setting or configuring authorization headers.

  • Set the Oracle-Mobile-External-Authorization header on each request.

    If you decide not to configure a security policy, then the next best course of action is to set the Oracle-Mobile-External-Authorization header for every request that the connector makes. When calling a connector API through custom code, an Oracle Mobile Cloud Service-specific authorization header is automatically set as the Authorization header. This original Authorization header that’s set on the connector API request is used to pass only Oracle Mobile Cloud Service authorization and is never passed through to the external service call. If you set Oracle-Mobile-External-Authorization on the request, the value of this header will be set as Authorization on the request to the external service. Set an Oracle-Mobile-External-Authorization header only when the service that you’re connecting to is secured in a way that isn’t described by an existing security policy. It won't take effect if one is configured. Setting this header takes precedence over setting an Authorization header and creating a rule for it.

    When setting this header, include BASIC to denote HTTP Basic Authorization or BEARER to denote OAuth. For OAuth, setting this header is applicable in cases where the OAuth token is passed by way of the Authorization header, such as in the following cases:

    • A REST connector is used to call another Oracle Cloud service. The same access token that was used to authenticate with MCS is reused to authenticate with the other service.

    • An access token generated by a service is passed to an MCS custom code call and set on a REST connector call to obtain the information about the individual who received the access token as part of an enterprise mashup.

    • A person logs on to Facebook and obtains a Facebook access token. The token is passed to an MCS custom code call and set on a REST connector call to retrieve the person’s friends list.

  • Configure a rule for the Authorization header.

    Lastly, when the Authorization header isn't already being set by other means, you can create a rule to apply a default Authorization header. On the Rules tab of the REST Connector UI, create a rule of type Header for Authorization and provide a value. This approach isn’t recommended as usually the Authorization header is dynamic or contains sensitive information (passwords). All sensitive information should be stored in a CSF key, which is why you should configure a security policy when possible.

Security Policy Types for REST Connector APIs

You'll need to set a security policy to protect the information you want to send or receive unless the service you’re accessing isn't a secure service or doesn’t support security policies, in which case, you can’t set a security policy for the connector. When determining what policies to set, consider whether the connection to the service involves transmitting proprietary or sensitive information. Adding a security policy ensures the authentication and authorization of the data transmitted.

From the Security page, you can select one or more Oracle Web Services Manager (Oracle WSM) security policies, including OAuth2, SAML, and HTTP Basic Authentication.

Security Policy Type Description

OAuth2 and the Client Credential Flow

Oracle Mobile Cloud Service supports OAuth2, a system where an Authentication server acts as a broker between a resource owner and the client who wants to access that resources. Of the different flows (security protocols) offered by OAuth2, the Client Credentials Grant Flow is used in Oracle Mobile Cloud Service to secure REST connections. This flow is used when the client owns the resources (that is, the client is the resource owner).

HTTP Basic Authentication

HTTP Basic authentication allows an HTTP user agent to pass a user name and password with a request. It's often used with stateless clients, which pass their credentials on each request. It isn't the strongest form of security though as basic authentication transmits the password as plain text so it should only be used over an encrypted transport layer such as HTTPS.

Security Assertion Markup Language (SAML)

SAML is an XML-based open standard data format that allows the exchange of authentication and authorization credentials among a client, an identity provider, and a service provider. The client makes a request of the service provider. The service provider verifies the identity of the client from the identity provider. The identity provider obtains credentials from the client and passes an authentication token to the client, which the client then passes to the service provider. The identity provider verifies the validity of the token for the service provider and the service provider responds to the client.

Ask yourself the following questions to determine what kinds of security policies you need:

  • What are the basic requirements of your security policy? Do you need to only authenticate or authorize users, or do you need both?

  • If you need only authentication, do you need a specific type of token and where will the token be inserted?

For a list of the security policies supported for REST Connector APIs, see Security Policies for REST Connector APIs. For descriptions of security policy properties that can be overridden, see Security Policy Properties.

CSF Keys and Web Service Certificates

Depending on the security policy that you selected, you may be able to override a property that sets a CSF key or a Web Service Certificate. In MCS, the Oracle Credential Store Framework (CSF) is used to manage credentials in a secure form. A credential store is a repository of security data (credentials stored as keys) that certify the authority of users and system components. A credential can hold user name and password combinations, tickets, or public key certificates. This data is used during authentication and authorization.

CSF lets you store, retrieve, update, and delete credentials (security data) for a web service and other apps. A CSF key is a credentials key. It uses simple authentication (composed of the user name and the password for the system to which you’re connecting) to generate a unique key value. You can select an existing CSF key or create one through the Select or Create a New API Key dialog. To select or create a CSF key, see Setting a CSF Key.

A Web Service Certificate allows the app to securely communicate with the web service. It can be a trusted certificate (that is, a certificate containing only a public key) or a certificate that contains both public and private key information. You override a certificate key by selecting an alias from the drop-down list. The certificate key available in some security policies for a REST Connector API is the keystore.sig.csf.key, which is the alias for this property that’s mapped to the alias of the key used for signing.

Important:

For security policies for REST Connector APIs, don’t override the default value for the keystore.sig.csf.key property. Currently, orakey is the only valid value for all certificate keys.

Not all security policies contain the same properties. When you select a policy, you can see which properties are listed in the Policy Overrides. For example, if you selected http_basic_auth_over_ssl_client_policy, then you’ll see that the policy contains the csf-key property but none of the certificate keys. However, if you selected http_saml20_token_bearer_over_ssl_client_policy, then you’ll see both the csf-key and the keystore.sig.csf.key certificate key.

Note:

It isn’t necessary to set all the overrides for a policy; however, you should be familiar enough with the security policies that you’ve selected to know which overrides to set for each policy.

CSF keys, certificates, and their respective values are specific to the environment in which they’re defined. That is, if there are multiple environments, A and B, and you’re working in environment A, then only the CSF keys and certificates for the security policies in use by artifacts in that environment are listed in the CSF Keys dialog. A different set of keys and certificates will be displayed in environment B. It’s also possible for keys with the same key name but with different values to exist in multiple environments.

A CSF key can be deployed to another environment, however, because CSF keys are unique to an environment, only the key name and description are carried over to the target environment. You won’t be able to use that key in the new environment until it’s been updated with user name and password credentials by the mobile cloud administrator.

Query and Header Parameters

A Query parameter is the most common type of parameter. Use it to filter, sort, and search for information. Add a question mark (?) to the end of the URL followed by a name-value pair. For example:

/directions/distance?origin=Los+Angeles&destination=Seattle

The query specifies that the information wanted is the distance from one location (origin=Los+Angeles) to another (destination=Seattle).

Note:

If you specify a parameter in the custom code and you also specify that same parameter in a REST connector rule, the parameter in the custom code takes precedence and overrides the parameter’s value defined in the rule.

Query parameters are usually set in rules, however, you can have query parameters in the remote URL. In such cases, there’s a precedence order for how the parameters are combined at runtime. See Setting Query Parameters in Remote URLs.

Use a Header parameter for outgoing requests. REST headers are a means of providing HTTP metadata. For example, the header, Expires, can be used to specify the amount of time after which a response is considered stale.

Setting Query Parameters in Remote URLs

You can add query parameters to the remote URL. If the remote URL contains a query parameter and you’re adding query parameters to the runtime resource through rules, then there is a precedence order of how the parameters are combined:

1. If you're adding a remote URL that has a query parameter U?qp=a to a runtime resource /r, the query parameter should come after the runtime resource.

For example, if you have the remote URL directions?origin=Pasadena and want to specify the runtime resource /zones, the full URL should be directions/zones?origin=Pasadena. Note that a simple concatenation of the URL isn’t done.

2. If you're combining a remote URL with a query parameter U?qp=a with a default rule qp=b , both query parameters should come after the URL.

For example, if you have a remote URL directions/zones?origin=Pasadena and you want to add the default rule destination=Anaheim, the resulting URL should be directions/zones?origin=Pasadena&destination=Anaheim. It’s orthogonal to rules.

3. If you're combining a remote URL U?qp=a with a runtime request /r?qp=c, the request parameter is appended to the URL.

For example, if you add the request /r?date=2015–04_07T14:30:00.000Z to the remote URL directions/zones?origin=Pasadena, the result isdirections/zones?origin=Pasadena&date=2015–04_07T14:30:00.000Z.

Adding Parameters

Parameters can be added as part of the URI path as a child (nested) resource or added as a query. There are no hard and fast rules as to whether to add parameters to the URI path or to add the parameters in a query. One possible consideration is whether the parameter is essential to the request. For example, you could use an identifier, id, to the directions resource in the URI path to get data for a specific area. If you’re using the parameter as a filter to narrow down the data, then add it in the query. For example, you could define office as a query parameter, .../directions/zones?office=Inglewood, to filter locations of offices only in the Inglewood area.

Besides the remote URL, you can set parameters in the following ways:

  • Setting a rule

  • Defining a request body

  • Defining a test endpoint

  • Creating custom code

The parameters are considered to be URL-encoded. If a parameter isn’t already URL-encoded, it will be encoded when sent to the external service.

Editing a REST Connector API

If you need to change some aspect of a connector API, you can as long as it’s in the Draft state. After you publish an API, the API can’t be changed. You’ll have to create a new version of a published connector and make your changes to the new version.

To edit a REST Connector API:
  1. Make sure that you’re in the environment containing the REST Connector API that you want to edit.
  2. Click side menu icon and select Applications > Connectors from the side menu.
    Now that at least one connector API exists, the Connectors page is displayed.
  3. Select the draft REST Connector API that you want to edit and click Open.

    You can filter the list by version number or status. You can also sort the list alphabetically by name or by last modified date.

  4. Edit the fields for general information, resources, and security policies as needed.

    For descriptions of the fields for creating a REST Connector API, see How Do I Access an Existing REST Service Using an Oracle Mobile Cloud Service Connector?

  5. Enter a new descriptor URL if needed. You’ll have to reenter your design time credentials if you enter a new descriptor URL.

    If you don’t want to change the descriptor, but you do want to get the latest available resources for that descriptor, proceed to the Resources page.

  6. Edit any rules that you set if needed.
  7. Click Refresh ( refresh icon to refresh list of resources) if you’re using the same descriptor and just want to get the latest resources.
  8. Click Save to test your changes immediately or click Save and Close to save your current changes and finish the rest of your changes later.
  9. Test your changes.

Your edited version is still in a Draft state and you can continue to edit your connector API until you’re satisfied with the configuration. At that point, you’re ready to publish your connector API. A published connector API can’t be changed. If you need to make changes you must create a new version of the connector API. To create a new version, publish, and deploy your connector, see Connector Lifecycle.

Using Your Connector API in an App

To use a connector in a mobile app, you first have to wrap calls to the connector API in a custom API and deploy that API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.

This allows the app to access the connector's functionality by calling the custom API. The syntax for a call to a connector API is the same as you would use when calling any other API from custom API implementation code. See Calling Connector APIs from Custom Code.

You make calls to connector APIs using JavaScript code in the custom API's implementation. When you implement a custom API, you can view the available connectors and their details in a special version of the API Catalog that’s available to custom APIs (the API Catalog that’s available to client apps doesn’t contain connector APIs). While creating your custom API, you might find it beneficial to open the Test page of the connector API so that you can refer to any headers, parameters, and schemas that you’ve configured for the connector API.

Troubleshooting REST Connector APIs

System message logs are great sources for getting debugging information. Depending on your role, you or your mobile cloud administrator can go to Administration in the side menu and click Logs to see any system error messages or click Request History to view the client (4xx) and server (5xx) HTTP error codes for the API's endpoints and the outbound connector calls made within a single mobile backend.

Sometimes a connection fails because the service URL provided is untrusted. You can add the URL to the list of trusted URLs at trustedsource.org. To learn more about what happens when you use an untrusted service URL and other common errors that can occur when configuring your connector API, see Common Custom Code Errors.

Issues can also arise when connecting to an external service such as when the service has an invalid SSL certificate or the request is redirected but the cookies aren’t preserved over the redirect. You can resolve these issues by using the options argument in custom code to customize the outgoing HTTP requests. See Overriding SSL Settings for Connectors for details.

By default, only TLSv1.1 and TLSv1.2 protocols are used for outbound connections. If you need to use an older version of a SSL protocol to connect to an external system that doesn't support the latest versions of SSL, you can specify the SSL protocol to use for the connector by setting the Security_TransportSecurityProtocols environment policy. The policy takes a comma-separated list of TLS/SSL protocols, for example: TLSv1, TLSv1.1, TLSv1.2. Any extra space around the protocol names is ignored. You can use the SSLv2Hello protocol to debug connectivity issues with legacy systems that don't support any TLS protocol. Note that this policy can’t be used to enable SSLv3 endpoints. See Environment Policies and Their Values for a description of the policy and the supported values. Be aware that this policy must be manually added to a policies.properties file that you intend to export.

Caution:

Be aware when setting the policy that older protocols are vulnerable to security exploits.