X

It's All About the Platform.

Understanding Web Services Through Specification Formats

Richard Bingham
Senior Development Manager

This short article introduces the specifications used to describe the Oracle Fusion Applications Cloud web services. We've had related questions on our forum so this is a getting-started explanation for applications administrators and developers who may be new to working with web services.

SOAP Web Services

For SOAP web services the specifications follow the industry-standard Web Service Description Language (WSDL) format to describe the operations and messages of each service. This includes protocol details, security information and parameters. Each WSDL file commonly references related WSDL documents and provide references to the message data, known as a Service Data Object (SDO). These SDO's are defined in XML Schema Definition (XSD) format and there is usually one for the main service message and others for each child object.

For example, the Sales Cloud 'Activity' service has the top level WDSL document accessible at the following URL: 

  • https://[YourCRMhost]/appCmmnCompActivitiesActivityManagement/ActivityService?WSDL

Within this is a reference to the data passed to/from this service is defined by the Activity SDO available at:

  • https://[YourCRMhost]/appCmmnCompActivitiesActivityManagement/ActivityService?XSD=/oracle/apps/crmCommon/activities/activityManagementService/Activity.xsd 

This Activity object has three child objects - Assignee, Contact and Objectives. These have their own XSD documents referenced from the parent:

  • https://[YourCRMhost]/appCmmnCompActivitiesActivityManagement/ActivityService?XSD=/oracle/apps/crmCommon/activities/activityManagementService/ActivityAssignee.xsd
  • https://[YourCRMhost]/appCmmnCompActivitiesActivityManagement/ActivityService?XSD=/oracle/apps/crmCommon/activities/activityManagementService/ActivityContact.xsd
  • https://[YourCRMhost]//appCmmnCompActivitiesActivityManagement/ActivityService?XSD=/oracle/apps/crmCommon/activities/activityManagementService/ActivityObjectives.xsd"

RESTful Web Services

RESTful web services currently exist for Fusion Cloud Application products Project Portfolio Management, Global Human Resources, and Sales. As shown in the Oracle API Catalog they also exist for many other Oracle Application products, including Service Cloud, CPQ Cloud, Eloqua & Responsis Marketing Cloud. Whilst commonality will occur, this article focuses on the two specifications that apply for understanding Fusion Cloud Application REST services.

1. Describe Format

Each web service provides a 'describe' endpoint URL which offers a descriptive document. This is an Oracle ADF way to understand a service, and is explained here as 'The describe for the RESTful web service allows you to identify the
shape and actions allowed on an ADF RESTful web service. It returns a
JSON object that contains the attributes, actions, and links defined in
the REST resource definition'. All Fusion Cloud Application RESTful services have such a describe document and is simply available by adding /describe to the service endpoint URL, such as:

http://[YourHCMhost]/hcmCoreApi/resources/latest/emps/describe 

Note here the use of /latest/ (or a specific release number) in the URL.

2. Open API Format

This is a language-neutral specification format for RESTful APIs. The format is an open industry standard and explained further on this GitHub page. Each Fusion Cloud Applications web service is defined in OpenAPI format on the Oracle API Catalog site. For example the Employees service has the following text which returns the related JSON file: OpenAPI Definition {···}.

Swagger is a tool to parse and manage the OpenAPI format information, and is used by the Oracle Documentation. The inputs into the Swagger tool can be found for each service under the 'download' feature on the following sites:

An example of using the Swagger client is available in the second half of this article.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.