Implementing Oracle E-Business Suite APIs as REST Services for Mobile Apps

Overview

Mobile apps exchange data with Oracle E-Business Suite through REST services provided through Oracle E-Business Suite Integrated SOA Gateway (ISG).

Oracle E-Business Suite Integrated SOA Gateway is an intrinsic part of Oracle E-Business Suite for service enablement. It allows web service clients to make use of the REST services provided from Oracle E-Business Suite. To accomplish this goal, it consists of many essential components. For example, Oracle Integration Repository, a key component that contains numerous interface endpoints exposed by applications throughout Oracle E-Business Suite. A service provider, a component that deploys Oracle E-Business Suite interfaces published in the Integration Repository as REST web services, as shown in the following diagram:

REST Service Provider Architecture

the picture is described in the document text

To better understand how Oracle E-Business Suite REST services can be used, the following topics are included in this chapter:

Understanding Oracle Integration Repository

Oracle Integration Repository is an essential component in Oracle E-Business Suite Integrated SOA Gateway. It is the centralized repository that contains numerous interface endpoints within the Oracle E-Business Suite. These integration interfaces can be built in native technologies or technology products such as PL/SQL, Java, Application Module Services, Concurrent Programs, XML Gateway, and Business Service Objects.

Oracle E-Business Suite Integrated SOA Gateway provides the functionality to expose these integration interfaces published in the Integration Repository as SOAP and REST based web services.

Note: Oracle recommends REST-based services for mobile apps.

Although Oracle E-Business Suite Integrated SOA Gateway is supplied as part of Oracle E-Business Suite, you need to configure Oracle E-Business Suite in order to use its functionality. See: Configuring Oracle E-Business Suite REST Services.

Configuring Oracle E-Business Suite REST Services

To access Oracle E-Business Suite REST services, if you have not configured Oracle E-Business Suite Integrated SOA Gateway (ISG), follow the setup and configuration steps as described in the following documents:

Note: Configuring Oracle E-Business Suite REST services provided through ISG is required only if you use Oracle E-Business Suite REST APIs for custom app development or use a sample app from Oracle E-Business Suite Mobile Foundation Login component. However, it is not required if you use standard Oracle E-Business Suite mobile apps installed from the Apple App Store or Google Play, or apps provided to users through enterprise distribution.

For information on custom app development for Oracle E-Business Suite mobile apps, see Using the Login Component to Develop Mobile Apps.

Implementing Oracle E-Business Suite REST Services

Once you have completed the required setup tasks on configuring Oracle E-Business Suite REST services, you can start implementing REST services for the mobile apps.

This section describes critical information on managing REST service lifecycle activities including searching and deploying your desired APIs as REST services, viewing deployed services through WADL descriptions, and granting user access privileges for the services. It also includes information on testing and troubleshooting these APIs during custom app development.

Implementing APIs as Oracle E-Business Suite REST Services

You can implement Oracle E-Business Suite REST services through the following ways:

Using Oracle Published Mobile APIs

Starting from Oracle E-Business Suite Mobile Foundation Release 6.1, Oracle provides APIs corresponding to selected functionality in the Oracle E-Business Suite mobile apps. These APIs are available in the Oracle Integration Repository where you can search, view, and deploy them as REST services for your custom app development.

For a list of the mobile APIs published in the Oracle Integration Repository for each app, see Oracle E-Business Suite Mobile APIs Available in the Oracle Integration Repository.

Important: Mobile APIs published in the Oracle Integration Repository have no dependency on Oracle E-Business Suite Mobile Foundation and therefore the availability of mobile app APIs in the repository is not limited to the apps developed based on Oracle E-Business Suite Mobile Foundation. For example, the "Oracle Mobile iProcurement for Oracle E-Business Suite" app is developed based on Oracle E-Business Suite Mobile Foundation, but the APIs published for that app can be used in another custom app that is developed using any other mobile development framework.

Before searching and using these APIs for your custom app development, you must apply required patches to make these APIs available in your Oracle E-Business Suite instance. For the patch information, see Applying Prerequisite Patches on the Oracle E-Business Suite Server, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2.

Use the following steps to implement these APIs as REST services in Oracle E-Business Suite:

  1. Search an Oracle E-Business Suite public interface that provides the desired functionality.

    All Oracle E-Business Suite mobile app APIs are categorized with same Business Entity Mobile Optimized API. This allows us to easily locate those APIs published for the mobile apps.

    In addition to the common business entity Mobile Optimized API for mobile apps, APIs can be associated with other business entities corresponding to their functional areas. For examples, each API published for "Oracle Mobile Approvals for Oracle E-Business Suite" (or the Approvals app) has two business entities associated with it:

    • Mobile Optimized API, the common business entity for all Oracle E-Business Suite mobile APIs

    • Workflow Notifications, a workflow related business entity specializing for the workflow area

    Note: You may search or browse interfaces by different categorizations such as product, business entity, or interface type.

    Interface types of PL/SQL APIs, Concurrent Programs, and Java-based APIs including Application Module Services and Java Bean Services can be published as REST services. Currently, all Oracle E-Business Suite mobile APIs are published as "Java" Interface Type and "Application Module Services" as Interface Subtype.

    Searching by Business Entity

    Once you log in to the Oracle Integration Repository through the Integrated SOA Gateway responsibility, click Search. The Search page appears where you can search and locate your desired mobile app's APIs.

    In the Search page, you can search mobile APIs by either of the following business entities:

    • Search by the common mobile business entity Mobile Optimized API to locate desired mobile apps' APIs in the repository.

      After all required patches for enabling mobile APIs available in Oracle E-Business Suite Mobile Foundation Release 6.1 are applied on your Oracle E-Business Suite instance, you can search by the common mobile business entity Mobile Optimized API to list all Oracle E-Business Suite mobile apps' APIs.

      Search Page with "Mobile Optimized API" Business Entity Highlighted

      the picture is described in the document text

      To limit the search result for your desired APIs, you can enter additional search values besides the Mobile Optimized API business entity. For example, to retrieve the APIs currently available for the Approvals app, you can enter "Applications Technology" as the product family along with the Mobile Optimized API business entity to locate the APIs for the Approvals app grouped under the "Applications Technology" product family.

      Search Page with "Mobile Optimized API" Business Entity Highlighted and a Specific Product Family as Search Criteria

      the picture is described in the document text

    • Searching by the business entity for a functional area (such as Workflow Notifications) along with other search criteria to locate desired APIs.

      All Oracle E-Business Suite mobile APIs available in the repository are published as "Application Module Services", a subtype of Java interface. To locate these APIs corresponding to the Approvals app's functionality, in addition to selecting Workflow Notifications as the business entity, you need to specify the 'Java' interface type first and then click the Show More Search Options link in the Search page. Select "Interface Subtype" in the Category field and then choose "Application Module Services" in the Category Value field before clicking Go to retrieve the search results.

      Search Page with Show More Search Options Fields to Search for Approvals App's APIs

      the picture is described in the document text

    Browsing by Product Family

    Alternatively, you can locate desired mobile APIs by browsing the list of interfaces displayed in a tree structure. In fact, the Browse feature appears by default when accessing the Oracle Integration Repository. In the left pane of the browse page, select 'Product Family' in the View By field and then expand the tree nodes to locate your desired product family, then product, and then business entity.

    For example, expand the Applications Technology product family node, and then the Workflow product node from the tree structure. Select the Mobile Optimized API business entity node to display the mobile APIs grouped under the Workflow product in the right pane of the page.

    Browse Page with View By "Product Family"

    the picture is described in the document text

  2. Create security grants for an interface.

    Oracle E-Business Suite Integrated SOA Gateway utilizes the Oracle E-Business Suite Function Security and Data Security features to ensure that only users with authorized privileges can access certain methods of an interface.

    Note that if your custom apps are developed based on Oracle E-Business Suite Mobile Foundation, the REST APIs consumed by the mobile apps should be granted to the respective mobile app access roles that you will create later during the server-side setup. Oracle E-Business Suite Mobile Foundation uses mobile app access roles to check if a user has the privilege to access the associated mobile apps and then loads relevant responsibilities for that user. See: Creating and Using Mobile App Access Roles.

    For information on creating security grants, refer to "Managing Grants for Interfaces with Support for SOAP and REST Web Services" in Administering Native Services chapter of the Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  3. Deploy an interface as a REST Service to an Oracle E-Business Suite application server.

    Once your desired interface is retrieved from a search, click the interface name to view the interface details. If the associated REST service is not available, you can deploy the interface as a REST service by entering the service alias and then clicking Deploy in the REST Web Service tab.

    For example, enter "approvals" as the service alias name for the "Approvals Details and Actions" interface and then click Deploy to deploy the interface as a REST service.

    Interface Details Page: REST Web Service Tab with "Not Deployed" REST Service Status

    the picture is described in the document text

    If the REST service is deployed successfully, "Deployed" should appear as the REST Service Status value indicating that the service is available for use on the Oracle E-Business Suite server.

    For more information about deploying REST services, refer to Administering Native Services chapter in the Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

  4. View the WADL description for a REST service from the Oracle Integration Repository.

    Once a REST service is successfully deployed, you can view the deployed WADL description by clicking the View WADL link in the REST Web Service tab.

    • WADL URLs are of the form:

      http://<hostname>:<port>/webservices/rest/<service_alias>?WADL

      For example, if approvals is used as the service alias for the "Approvals Details and Actions" interface (oracle.apps.fnd.wf.worlist.service.rt.server.WFNotifDetailsServiceAMImpl), after you deploy the service, the REST service WADL URL could be like:

      http://<hostname>:<port>/webservices/rest/approvals?WADL

      REST Web Service Tab with "Deployed" REST Service Status and View WADL Link Highlighted

      the picture is described in the document text

      Refer to "Reviewing WADL Element Details" in Discovering and Viewing Integration Interfaces chapter of the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

      • REST services support the following authentication types:

        • HTTP Basic Authentication

        • Oracle E-Business Suite Security Token-Based Authentication

        For more REST service security, see "Managing Web Service Security" in Securing Web Services chapter of the Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

      • REST services expect Oracle E-Business Suite security context values in the RESTHeader element of the HTTP requests.

      • REST services support REST messages in XML or JSON format.

        Refer to "Understanding REST Messages" in Discovering and Viewing Integration Interfaces chapter of the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Before using a deployed REST service for your custom app development, you need to test it first to ensure it can be invoked successfully once the required credentials and input payload are provided. See: Testing and Validating the REST Services.

Implementing Custom Interfaces

Creating Custom Interfaces

If there is no interface that meets your requirements or if you need additional interfaces for your custom mobile app, you can create custom interfaces of any interface types that can be exposed as REST services by using any technology available in Oracle E-Business Suite Integrated SOA Gateway. Annotate the custom interfaces based on the annotation standards and then upload them to the Integration Repository.

Note: When you implement REST services for use in custom mobile apps, it is important to implement the interface in a way as lightweight as possible, that is, focusing on the specific data being retrieved or other operation being performed. It is not recommended that you wrap an existing interface for use in custom mobile apps if the exact internals of that interface are not known.

For more information about creating custom interfaces, refer to Administering Custom Integration Interfaces and Services chapter in the Oracle E-Business Suite Integrated SOA Gateway Implementation Guide. For annotation information and guidelines, see Appendix A Integration Repository Annotation Standards in the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide. For information on uploading annotated custom interfaces to the Oracle Integration Repository, see "Generating and Uploading iLDT Files" and "Uploading ILDT Files to Integration Repository" in Administering Custom Integration Interfaces and Services chapter of the Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Implementing Custom Interfaces as REST Services

Custom interfaces are categorized with Interface Source "Custom" in the Integration Repository, in contrast to Interface Source "Oracle" for Oracle seeded interfaces in Oracle E-Business Suite.

Once annotated custom interface definitions are successfully uploaded to the Integration Repository, you can locate them in the main Search page. First, click the Show More Search Options link, and then select "Custom" from the Interface Source drop-down list, along with desired business entity, interface type, or product family if needed before clicking Go to run the search.

After locating the desired custom interfaces from the repository either through a search or browse from the tree nodes, you can deploy the custom interfaces as REST services by following the rest of the tasks as described earlier in Using Oracle Published Mobile APIs. These tasks include creating security grants, deploying the interfaces as REST services, and viewing the deployed WADL descriptions.

Testing and Validating the REST Services

Once a REST service is deployed on an Oracle E-Business Suite's application server, this deployed service is available and ready to be invoked.

Before you use the deployed REST service in a custom mobile app, it is important to test the REST service directly using a REST client, the same way it would be invoked in a mobile app flow. For example, a typical flow when a mobile user uses a mobile app is as follows:

  1. Log in to the app.

  2. Select a responsibility (and an organization in some apps) that initializes required application context.

  3. Navigate mobile app pages that invoke REST services to retrieve and display data.

  4. Log out of the app.

Following steps explain how the REST services can be tested:

  1. Testing the Login Service

  2. Testing the Initialize Service

  3. Testing Your Mobile REST Services

  4. Testing the Logout Service

If Oracle E-Business Suite Mobile Foundation Login component is used to develop custom mobile apps, you are not required to invoke the Login, Initialize and Logout services. These service invocations are pre-built into the seeded flow of the Login component where the user is required to log in to the app using the default login page, select a responsibility to initialize the Oracle E-Business Suite session context if required, and log out from Springboard. You are only required to design mobile app pages and invoke your app's REST services. For more details on how to develop custom apps using the Login component, refer to Using the Login Component to Develop Mobile Apps and Using the Sample App as a Reference.

If you do not use the Login component for your custom app development, then you will have to leverage the Login, Initialize, and Logout services as allowed by the development framework you plan to use.

Testing the Login Service

The Login service (http://<hostname>:<port>/webservices/rest/AuthenticationService?WADL) authenticates Oracle E-Business Suite mobile app user's credentials based on the HTTP Basic authentication scheme. It takes the user name and password provided in the "Authorization" HTTP header of the GET request. The user name and password are concatenated as username:password, and encoded to base64 format. If the login is successful, it returns a unique access token (Oracle E-Business Suite session ID) as the Set-Cookie header and also in the body of HTTP response.

The access token from the Login service that points to the user session will be passed as the Cookie HTTP header in all subsequent REST service calls for user authentication, without the need for the user name and password to be sent every time.

To better understand how to test and validate the Login service, a sample request to the Login service and a response from the Login service are included as follows:

Testing the Initialize Service

Once the Login service succeeds, the Initialize service (http://<hostname>:<port>/webservices/rest/AuthenticationService?WADL with the POST HTTP method) is optionally invoked to initialize the Oracle E-Business Suite session with required responsibility and organization contexts to authorize the application data access only to appropriate users.

For example, if an Oracle E-Business Suite mobile app requires the responsibility context in order to access specific Oracle E-Business Suite data, after the user login, a list of responsibilities is displayed. The user needs to select a responsibility (and an organization if needed) required for invoking the Initialize service.

Perform the following tasks to test and validate the Initialize service for the security context:

  1. Identify the required security context for your app's REST services:

    • Responsibility context only

      If only the responsibility context is required, specify the Responsibility ID and Application ID to test the service.

      Note: The Initialize service always initializes the responsibility context in the Oracle E-Business Suite session.

    • Responsibility context and organization context

      If both the responsibility context and organization context are required, specify the responsibility details with Organization ID.

      Apart from initializing the responsibility and organization contexts in the Oracle E-Business Suite session, some seeded REST services may require Organization ID to be passed as an input parameter to the REST services. In such cases, pass the selected Organization ID to those REST services as input so that the services can retrieve data using an appropriate organization context.

    • Any additional context other than the responsibility context or organization context that is required to be initialized for the app-specific REST services.

  2. Invoke the Initialize service.

    • Following is a sample request to the Initialize service:

      POST /webservices/rest/initialize HTTP/1.1
Cookie: demo=xxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/xml

<data>
        <resp>
                <id>20872</id>
                <applId>178</applId>
        </resp>
        <securityGroup>
                <id>0</id>
        </securityGroup>
        <org>
                <id>1733</id>
        </org>
</data>

      The HTTP headers and input parameters used in this sample request are:

      • Cookie: Access token from the Login service in the format of <accessTokenName>=</accessTo>

      • Input payload

        • Responsibility details, such as Responsibility ID and Responsibility Application ID

        • Security group ID

        • Organization ID

      Note: Instead of passing values as ID, the key values can also be passed as the following example input payload.

      <data>
        <resp>
                <key>SYSTEM_ADMINISTRATION</key>
                <applKey>ICX</applKey>
        </resp>
        <securityGroup>
                <key>STANDARD</key>
        </securityGroup>
        <org>
                <key>CM1</key>
        </org>
</data>

    • Following is a sample response from the Initialize service.

      Set-Cookie: JSESSIONID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/xml

<?xml version = '1.0' encoding = 'UTF-8' ?>
<response>
<data>completed with values resp_id=20872, resp_key=SYSTEM_ADMINISTRATION, appl_id=178, appl_key=ICX, sec_group_id=0, sec_group_key=STANDARD, org_id=1733, org_key=Vision Communications (USA)</data>
</response>

Testing Your REST Services

Once your desired API is deployed as a REST service (http://<hostname>:<port>/webservices/rest/<service_alias>?WADL) from the Oracle Integration Repository, you can use the deployed REST service to fetch Oracle E-Business Suite data for your mobile app.

Perform the following tasks to invoke the REST service using the security token:

  1. To invoke a REST service, insert the Cookie headers from the Login service. Create payload as required by the REST service.

    Note: You can use any Integrated Development Environment (IDE), such as Oracle JDeveloper, to create a sample request payload from the XSD associated with the REST resource. References to different REST resources (APIs) and corresponding XSDs for request and response are available in the WADL file.

    A sample request payload for invoking a REST service is as follows:

    POST /webservices/rest/<service_alias>/<rest_method> HTTP/1.1 
Cookie: demo=xxxxxxxxxxxxxxxxxxxxxxxxxx 
Accept-Language: en-GB,en-US;q=0.8,en;q=0.6
Content-Type: application/xml

<restMethod_Input xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns="http://xmlns.oracle.com/apps/fnd/rest/servicealias/restMethod">
<InputParameters>
        <parameterOne>valueOne</parameterOne>
        <parameterTwo>valueOne</parameterTwo
</InputParameters>
</restMethod_Input>

    Note: Once the Initialize service is invoked to initialize the required responsibility and organization contexts for a given session identified by a session token from the Login service, the contexts apply to all REST service invocations that use that session token. You must not include the <RESTHeader> element in the REST service requests.

    However, if your REST service requires application contexts that are different from the ones initialized using the Initialize service for the session, you must pass them as part of the <RESTHeader> element of that specific REST service request.

  2. To perform the language testing for the REST service, use the Accept-Language HTTP header of the REST service request and send value in RFC 5646 language format. For example, <lang>-<COUNTRY>.

    Oracle E-Business Suite Integrated SOA Gateway always checks the language information of an incoming REST service call and resets the language in the Oracle E-Business Suite session. If no language is set in the REST header, then the session language defined through the ICX_LANGUAGE profile option is used as the Oracle E-Business Suite user's language.

Testing the Logout Service

The Logout service (http://<hostname>:<port>/webservices/rest/AuthenticationService?WADL) invalidates the current Oracle E-Business Suite session.

To invoke the Logout service, insert the Cookie headers from the Login service, especially Cookie:<accessTokenName>=<accessToken>.

A sample request for the Logout service is as follows:

GET /webservices/rest/logout HTTP/1.1
Cookie: demo=xxxxxxxxxxxxxxxxxxxxxxxxxx

To invalidate the current Oracle E-Business Suite session, send a GET request to the Logout service using the current session's security token in the Cookie header. The request does not require any payload.

Troubleshooting Tips

For troubleshooting information on potential problem symptoms and corresponding solutions, refer to the following documents for your Oracle E-Business Suite: