APEX: Extending Fusion /describe
Sydney Nurse
Oracle provides Cloud Infrastructure and Applications services via its globally distributed data centres. The Software as a Service (SaaS) suite provides business applications in many functional areas.
SaaS, offers many benefits to organisations such as hands-off architecture deployment and infrastructure management, standardised processes, a configuration driven customisation.
Oracle SaaS, commonly known as Fusion Cloud Apps or Fusion, provides the ability to develop components and user interfaces with cloud tools that have been embedded into its deployment, and yet many customer seek out options to build extensions through integration or access to data that is 100% under there control.
As with all applications the 80/20 functional coverage still applies and though configuration changes are nice, there are still use cases for extension or cull custom development.
Hence the need to integrate and in today’s world, REST APIs are king.
About this Post
In this post, I will explore the Fusion SaaS APIs, using methods that are common to suite of applications and its REST APIs, in addition to the documentation.
APEX 23.2 provided many new features:
The last driving interest and requests for demonstrations, comparisons with other services, and a rush to get up to speed with Fusion integration.
The What’s New site for 23.2 provides overviews and demonstrations of all of these features, including the Support for Fusion Apps Extensions feature. It looks fantastic and then as my tests began, so did my struggles.
Enterprise applications provide a vast range of functional areas with related and required data entry sequences and constraints. A request to perform background checks on the candidates of job postings leverages several API calls to Fusion alone.
Get the job openings, show display values not the codes, name and details of candidates, hiring managers, recruiters, etc. all to provide similar access to data in Fusion while enhancing it with requests and responses of 3rd party services.
Obviously I started with the documentation and reached out to PMs and other knowledgeable contacts but this was and still is a relatively new feature.
Before Getting Started
Fusion SaaS has many functional areas and for the un-initiated is very complex. The first bus stop is to find a SaaS consultant that is willing to explore app integration topic with you and provide SME point of view & guidance. In my opinion they will be new to this as well but the knowledge and experience about the data entry flows, dependencies and how to validate the data is key to the project’s success.
No journey begins with out documentation, and these are some of the better pages that I’ve had the pleasure to turn. Stick to the area of your use case, the Common Features in Oracle Fusion Cloud Applications, and the Security Reference for Common Features & security reference for the specific SaaS module.
Each set of REST API documentation contains a Quick Start section (HCM, Sales & CX, etc.) with an overview of the supported authentication methods, connection examples and response using Postman.
I would recommend the following sections on Use Cases and Learn More, which is where we will start our journey, Access Metadata.
Let’s Get Into It
REST API Metadata
What is it, can it help me consume a published API and how do I access it?
Metadata is data that describes other data and allows developers to and fully understand the APIs input, output, methods and usage requirements. Oracle supports the OpenAPI Document standard for self-describing its APIs and Fusion SaaS conforms to the OpenAPI specification.
When describing a Fusion SaaS RESTful service, it contains a comprehensive description, including the object resource URIs, attributes, supported actions, child resources, and list-of-value (LOV) resources. (well, according to the docs ;) )
The metadata will contain all attribute properties, annotations, data type, required / mandatory, allowed actions like update and use in queries, a comprehensive list of all the collections, functions and links, available HTTP methods, and importantly the response of each request.
/describe
All of the REST APIs have a GET method /describe endpoint to retrieve its metadata. e.g. resources/<version>/absences/describe or resources/<version>/<task>/describe
For each resource and task area, we will have a complete picture and description of all attributes that are required. The documentation includes some of these details but is not all inclusive in a single source.
APEX REST Source Catalog
!Straight from the documentation!
REST Source Catalogs contain metadata about REST Data Sources. Developers can search and browse a catalog and then create REST Data Sources for their applications.
You can share REST Source Catalogs by exporting the REST Data Source catalog to a file and then importing it into another workspace or another instance.
Using Postman or cli, we can save the response to file and create a new Catalog in APEX.
- Create a new Catalog from OpenAPI file
Set the attributes for the catalog
Group
Set the REST Source Type to Oracle Cloud Applications
Set the Authentication method to Basic Authentication
For Oracle Cloud Applications
- Set the request/response properties
View the available APIs by selecting the # services in the contents column.
From any application in the workspace, simply import the REST Source from the catalog to use in the project.
An Alternative → Oracle Cloud Apps REST Data Source Explorer
Installing the Oracle Cloud Applications REST Data Sources Explorer, from the Utility section in the apps gallery, helps you retrieve useful, searchable reference info about them including business object attributes and child objects available. It also lets you discover what other REST endpoints are available for use.
Once an application, contains an Oracle Cloud Applications configured REST Data Source, it can be explored in this application.
Click the Static ID of the REST Data Source to explore attributes. A classic report displays the list of attributes and its details.
Endpoints for select list and child objects should be provided, but this is not always the case for select lists.
If the LOV Endpoint column is empty, use /describe to retrieve the additional details.
Conclusion
Access to Metadata for APIs is very useful and in the case of complex applications, such as Oracle Fusion SaaS (Oracle Cloud Applications), attributes and methods is essential to any integration project and app development.
Standard support for OpenAPI document specification simplifies creating APEX REST Data Sources through catalog imports.
The Oracle Cloud Applications REST Data Sources Explorer is a great place to start exploring the Fusion SaaS APIs but requires a configured Oracle Cloud Applications REST Data Source in the workspace. It presents the attribute and child objects for the single task endpoint.
The /describe method is available on all Fusion SaaS REST APIs and provides the most comprehensive details about the API, including the ability to get all metadata for all available REST APIs.
Subscribe to my newsletter
Read articles from Sydney Nurse directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
Sydney Nurse
Sydney Nurse
I work with software but it does not define me and my constant is change and I live a life of evolution. Learning, adapting, forgetting, re-learning, repeating I am not a Developer, I simply use software tools to solve interesting challenges and implement different use cases.