Oracle SaaS | Analysing the Structure and Morphology of the REST API Methods


Oracle SaaS API’s have a structure that is equal for all the “business entities” across the different modules (Finance, Loyalty, Supply Chain, …) such as invoices, expenses, loyalty transactions and so on. Let’s analyze the pattern. In this episode, we are focusing on the “Get all xxx” methods because it conforms a pattern that we’ll utilise in a sooner construct which we are working on for building a tool that extracts and publishes changes in the data in near-realtime.

Verb

Verb for all of them is obviously GET

Endpoint

Endpoint is <fqdnurl>/<endpoint> where

<fqdn> is the server url such as https://iiii-eeee.fa.em2.oraclecloud.com
<endpoint> is the API endpoint provided in the documentation such as /fscmRestApi/resources/11.13.18.05/invoices 

Data Retrieved

If you execute the API call and data exists, conditions are valid and the user you are using for the connection has privileges to read, a JSON structure is retrieved up to the number of records in the limit parameter (default 25). If more records exist it is notified in the hasMore field in the response.

Parameters

expand: Includes child records of the entity, you can specify which childs to include or all for example ?expand=invoiceLines (tip: if onlyData is false (default) the links provide you the name of the child entities)
fields: If you don't want all the fields in the response, include the names of the fields expected
limit: maximum number of records per call execution
offset: the ordinal number of the set of records retrieved according to the total and the limit parameter. For example if limit is 5 and you want the records from 6 to 10, offset must be set to 1
onlyData: by default, response JSON includes child objects links, putting this value to false disables that option
orderBy: fields and order criteria for retrieving data such as ?orderBy=InvoiceId:asc,SupplierSite:desc
q: the filter condition to get data such as ?q=InvoiceAmount>1000
totalResults: by default is false so total records retrieved are not evaluated, if true they are counted with the drawback of a more computation cost and probably lower response time and performance
totalResults effect
Get all banks REST API
Get all expense records API
Get all invoices API

Example

In the following example we are requesting invoices and their lines with an amount greater than 1000 indicating that we want to know the number of invoices that accomplish the criteria

curl -X GET -k -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json' -u jxvxxr.mxgxxtx@xrxclx.cxm:password "https:/iiii-eee.fa.em2.oraclecloud.com//fscmRestApi/resources/11.13.18.05/invoices?limit=5&totalResults=true&q=InvoiceAmount>1000&expand=invoiceLines&onlyData=true"

Result

{
  "items" : [ {
    "InvoiceId" : 1,
    "InvoiceNumber" : "DFS03",
    "InvoiceCurrency" : "EUR",
    "PaymentCurrency" : "EUR",
    "InvoiceAmount" : 1100,
   …
    "CreationDate" : "2019-07-10T08:33:13+00:00",
    "CreatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
    "LastUpdatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
    "LastUpdateDate" : "2019-07-16T12:46:37+00:00",
    "LastUpdateLogin" : "8AC9D26BC392042BE053A46F660ACD78",
    "invoiceLines" : [ {
      "LineNumber" : 1,
      "LineAmount" : 1000,
      "AccountingDate" : "2019-07-10",
      …
      "MultiperiodAccountingAccrualAccount" : "",
      "CreatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
      "CreationDate" : "2019-07-10T08:33:18+00:00",
      "LastUpdateDate" : "2019-07-10T08:34:56+00:00",
      "LastUpdatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
      "LastUpdateLogin" : "8AC9F283AC3E043EE053A46F660A9D93"
    }, {
      "LineNumber" : 2,
      "LineAmount" : 100,
      "AccountingDate" : "2019-07-10",
      …
    } ]
  }, {
    "InvoiceId" : 1001,
    …,
    "invoiceLines" : [ {
      "LineNumber" : 1,
      "LineAmount" : 1000,
      …
    }, {
      "LineNumber" : 2,
      "LineAmount" : 100,
      …
    } ]
  }, …
    } ]
  } ],
  "totalResults" : 155,
  "count" : 5,
  "hasMore" : true,
  "limit" : 5,
  "offset" : 0,
  "links" : [ {
    …
}

So far, so good! Please note we have highlighted CreationDate and LastUpdateDate in the records, w’ll se the reason in a new post sooner, stay tuned!

So that’s all folks for now, hope it helps! 🙂

More Info

Oracle Cloud Applications Documentation Index

REST API for Finiancials

REST API for Supply Chain & Manufacturing

And so on… locate the REST API on the left panel of the documentation for each module listed in the index

One thought on “Oracle SaaS | Analysing the Structure and Morphology of the REST API Methods

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.