24 REST Connector APIs
Oracle Mobile Cloud Service (MCS) enables you to create connector APIs to connect to external REST services. You can then call these connector APIs from the implementations of your custom APIs.
How REST Connector APIs Work
A REST connector API is an intermediary API for calling REST endpoints in enterprise systems or third-part APIs. The connector API takes the form of a configuration that gives your apps a standard way to connect to these REST services and take advantage of the security, diagnostics, and other features provided by MCS.
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 (but only in JSON for services based on Swagger descriptors).
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.
REST Connector API Design Process
Here’s the process for designing a REST connector API:
-
Create REST Connector API. You create an API with the REST Connector API wizard in MCS.
-
Authenticate Access to Descriptor Instances with Design Time Credentials. The design time credentials are saved as a Credentials Store Framework (CSF) key in MCS.
-
Connect to Descriptor Instance. If you provided a Swagger 2.0 descriptor URL, a connection to the descriptor is made.
If you provide a remote service URL, you connect to the external service.
-
Discover Resources. 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. -
Set Rules. Optionally, you can set rules after you have selected the desired resources or after you have connected to the external service.
-
Examine and Set Resources. 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.
-
Set Security Policies. You configure the Oracle Web Services Manager (Oracle WSM) security policy to be used at runtime.
-
Test REST Connector API. You test the endpoint using mobile user credentials.
Why Use Connectors Instead of Direct Calls to External Resources?
Using a REST Connector API provides you with the following benefits over making direct calls from your app code to external resources:
-
Allows for simplified declarative connection and policy configuration.
-
With a Swagger descriptor, determines the available resources and creates endpoints for you.
-
Provides you with extensive diagnostic information as its tightly integrated with the MCS 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.
Creating a REST Connector API
Use the REST Connector API wizard to create, configure, and test your connector API.
To get a basic working connector API, you can provide as little as a name for the connector API and a URL to the external service.
From there, you can:
-
Define rules to form specific requests or responses for the data that you want to access.
-
Configure client-side security policies for the service that you’re accessing.
-
Test the connection and test the results of calls made to the connection.
You must create a custom API and implementation to enable your apps to call the connector APIs. To generate the API and implementation automatically, see Generating Custom APIs for Connectors. If you want to do this manually, create a custom API with the appropriate resources, and then implement the custom code as described at Calling Connector APIs from Custom Code.
Basic Connector Setup
You can create a functioning connector by completing the first two pages in the REST Connector API wizard.
-
Make sure that you’re in the environment for which you want to create the REST Connector API.
-
Click and select Applications > APIs from the side menu.
-
Click REST (if this is the first connector API to be created) or New Connector and from the drop-down list, select REST.
-
Identify your new REST Connector API by providing the following:
-
API Display Name: The name as it will appear in the list of connector APIs.
-
API Name: The unique name for your connector API.
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.
Other than a new version of this connector API, no other connector API can have the same resource name.
-
Short Description: This description will be displayed on the Connectors page when this API is selected.
-
-
Click Create.
-
In the General page of the REST Connector API dialog, set the timeout values:
-
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 thepolicies.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.
-
-
Click Descriptor and enter the connection info for the service.
If you provide a Swagger descriptor URL, the available resources are identified and displayed, and you can select which ones you want.
Note:
Only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port. -
Click Save.
-
Optionally, click Test, select authentication credentials, and make test calls to the service.
From there, you can further configure the connector in the following ways:
-
(If you have provided a descriptor on the Descriptor page) navigate to the Resources page and select the methods for the exposed resources.
-
Define rules.
-
Set security policies.
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
Note:
Only Swagger metadata in JSON format is currently supported.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 create one or more rules. Each rule can have one or more parameters of type Query
and Header
.
If no rules are applied, all calls are passed through the proxy to the existing service.
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
andPUT
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
Security Policies and Overriding Properties
If you want to use headers, see Security and REST Connector APIs.
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:
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 thecsf-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 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.
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:
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
To test your connector with the endpoints exposed for you:
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.
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 |
204 NO CONTENT |
Successful connection but no response body (used for |
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.
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 MCS-specific authorization header is automatically set as theAuthorization
header. This originalAuthorization
header that’s set on the connector API request is used to pass only MCS authorization and is never passed through to the external service call. If you setOracle-Mobile-External-Authorization
on the request, the value of this header will be set asAuthorization
on the request to the external service. Set anOracle-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. Passing theOracle-Mobile-External-Authorization
header in the connector request takes precedence over an Authorization header rule.When setting this header, include
BASIC
to denote HTTP Basic Authorization orBEARER
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 defaultAuthorization
header. On the Rules tab of the REST Connector UI, create a rule of typeHeader
forAuthorization
and provide a value. This approach isn’t recommended as usually theAuthorization
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 |
MCS 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 MCS 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 thekeystore.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
).
You can see in the example above that the space in the query parameter, Los Angeles, is encoded by a plus sign, (+
). The Url_PercentEncodeQueryParameterSpaces
policy determines how spaces in query parameters are encoded. If set to true
, a space is encoded as a percent sign, (%
). If set to false
(the default value), a space is encoded as a plus sign (+
).
For example, if Url_PercentEncodeQueryParameterSpaces
is set to true
, the outbound URL would be .../distance?origin=Los%Angeles&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.
- Make sure that you’re in the environment containing the REST Connector API that you want to edit.
- Click and select Applications > APIs from the side menu.
- Select the draft connector API that you want to edit and click Open.
- Click Refresh ( ) if you’re using the same descriptor and just want to get the latest resources.
- 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.
- Test your changes.
Using Your Connector API in an App
To use a connector in a mobile app, you need to have a custom API that can call the connector API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.
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.
When you implement a custom API, you can view the available connectors in the API Catalog tab in the API Designer. 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.
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.