1. Learn how to access data from an Oracle Mobile Hub application
  2. Learn About Custom API Design

Learn About Custom API Design

In Oracle Mobile Hub, you can create custom REST APIs that can be used by your mobile apps.

If you’re a mobile app developer, use the API Designer to sketch out and test the endpoints that you define and then have a service developer fill out the details of the API (add resource types or traits, provide a schema, and set the access to the API and its endpoints), and implement it in JavaScript. If you’re a service developer, use the API Designer to explicitly configure a complete API that you can test with mock data. Alternatively, you can generate custom APIs from a REST or Fusion Applications connectors without writing any code.

Unlike the Oracle Mobile Hub platform APIs, which provide a core set of known services, custom APIs let you use Node.js to code any service your mobile app needs, published through a REST interface. You can relay data by using an Oracle Mobile Hub connector to a backend service, which transforms complex data into mobile-friendly payloads. By using custom APIs to build a catalog of reusable services, you can save a lot of time that might otherwise be spent periodically re-creating and maintaining implementation details in your mobile applications.

About the API Design Process

The API Designer guides you through the process of creating a custom API.

You can quickly create a draft version of the API in just a few steps:

  1. Add the basics (name of the API, the message media type, and a brief description).

  2. Define an endpoint by setting a resource and at least one method for it.

  3. Set access security.

  4. Test your endpoint after you define at least one resource.

You can create mock data to quickly test and validate an endpoint even when you haven’t completely finished configuring your API. When you define your message body, you can provide placeholder values to verify that the correct data is being sent or returned.

To fully complete your API, use the API Designer to help you add the essential components for a robust API:

  • Provide the API metadata (that is, the basic attributes of the API, which are the API display name, API name, and short description) or, if you already have a RAML document that contains the configuration of your API, then you can upload it to the API Designer. All the information (metadata, resources, methods, and the schema for the message body) is extracted from the RAML document and loaded into the API Designer, letting you quickly proceed to testing your endpoints or editing your API configuration.

  • Add one or more root and nested resources.

  • Add methods to act on the resources.

  • Create a schema to describe the body of data.

  • Test your endpoints during design time with sample data and make any changes as needed.

  • Allow anonymous access to your API, or specify which roles can access it.

  • Add documentation for your custom API

Later on, as you create more APIs, you might find that you are repeatedly defining the same methods, and using the same parameters, etc. You can reduce the redundancy by creating resource types and traits. If your API is still in the draft state, then you can go back into your configuration and add the resource types and traits that you defined.

About Generating Custom APIs for Connectors

Oracle Mobile Hub can generate custom code from connectors to connect to external services. As a service developer, you can select an Oracle Fusion Applications connector or a REST connector that was created with a valid descriptor, generate the custom API, and use the generated API to make it easier to call these services from the implementations of your custom APIs, or directly from a mobile application.

A connector is a way to enable a mobile backend to communicate with an external service such as an enterprise system or third-party APIs, which in turn, allows a mobile application 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.

As a service developer, you can generate a custom API that exposes the methods of a connector API and provides a default implementation without writing code.

The custom API is generated with an endpoint for each resource in the connector API, and it's opened in the API Designer for you to continue to specify details of the API, such as roles. The default implementation, which passes through all the requests coming from the generated custom API to the target connector API, is also generated and assigned to the generated API. As soon as you have assigned roles to the API if they are required for security on the connector you can use the implementation to test the API. You can download and modify the implementation and then upload it.

Being able to create a custom API for a connector means that it's much easier to create a prototype that you use to test a connector. As you find things you want to change, you can quickly make a change to the connector, and generate a new custom API and implementation. When you're satisfied, you can generate a final version of the custom API and implementation.

  • Develop a REST connector or Oracle Fusion Cloud Applications connector that's defined using a descriptor.
  • Generate the custom API from the connector. It opens in the API Designer, where you can define one or more roles or specify the authentication required by the API.
  • You can immediately call the generated API from the mobile device. The default implementation passes through all the requests coming from the generated API to the target connector API.
  • You will probably want to download the implementation and modify it to shape the data returned.
  • You may want to revisit the connector and make changes to the connector resources or descriptor. If you do you must generate a new custom API and implementation. If you make changes to the generated custom API, these changes aren't reflected in the connector. You should make the appropriate changes in the connector and then generate the custom API and implementation again.

You can only generate a custom API for a REST or Oracle Fusion Cloud Applications connector, which is defined using a descriptor. You can't generate a custom API for another type of connector, or where the REST or Oracle Fusion Cloud Applications connector doesn't have a descriptor.

If you want to send multipart form data or use the http options object, you might need to replace the callConnector method in the implementation with your own code.

REST Connector APIs

You can 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-party 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 Oracle Mobile Hub.

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.

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 because it's tightly integrated with the Oracle Mobile Hub 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.