Working with the Resource Catalog

About the REST API Catalog Describe

REST APIs support retrieving a describe for all the available resources in the resource catalog, it returns JSON objects that contain the attributes, actions, and links defined in the REST resource definitions for the business object.

The describe for the REST API resource catalog allows you to identify the shape and actions allowed on a REST API defined for the service endpoint. By default the catalog describe request returns a JSON object that contains the information needed to understand all available resources.

REST APIs support the following catalog describe use cases:

Retrieve a resource catalog describe, where the describe details will be limited to resource titles and links only and children, or nested resources, will be excluded.
Retrieve a resource catalog describe but optionally exclude or include children resources nested within a parent resource and optionally exclude or include all resource annotations.

To retrieve the catalog describe of all the available, parent resources in the application, you append /describe to the base URL with the query parameter metadataMode set to minimal:

http://<base_url>/describe?metadataMode=minimal

Additionally, you can append URL query parameters on the request for a minimal catalog describe to retrieve specific details in the describe. For example, the following URL with appended query parameters retrieves a minimal catalog describe with all available children resources nested within their parent resources included.

http://<base_url>/describe?metadataMode=minimal&includeChildren=true

The following table identifies the URL query parameters the may be used with the catalog describe request. These query parameters let you control the amount of detail retrieved in the describe.

Table 2-1 Optional URL Query Parameters for Catalog Describe Requests

URL Query Parameter Values Description

URL Query Parameter	Values	Description
`includeChildren`	`true`, `false` (default)	Use to include all available children resources nested within a parent resource describe. You can append `&includeChildren=true` on the describe request. For a resource catalog describe example, see Retrieving the Resource Catalog Describe.
`showAnnotations`	`true`, `false` (default)	To include resource annotations in the catalog describe, you can append `&showAnnotations=true` on the describe request. Note that annotations must be defined by the web developer and may not be present on the resource.

includeChildren

true, false (default)

Use to include all available children resources nested within a parent resource describe. You can append &includeChildren=true on the describe request.

For a resource catalog describe example, see Retrieving the Resource Catalog Describe.

showAnnotations

true, false (default)

To include resource annotations in the catalog describe, you can append &showAnnotations=true on the describe request.

Note that annotations must be defined by the web developer and may not be present on the resource.

Retrieving the Resource Catalog Describe

REST APIs support describing all available resources while retrieving a reduced amount of information for the application end point using a GET method. The reduced or minimal catalog describe helps improve the readability of the describe by limiting the resource information to resource titles, links, and available annotations.

To examine the minimal describe for all available resources in the resource catalog:

Execute the minimal resource catalog describe and locate the names of the resources in the describe. Note that nested resources or children resources are not shown by default.
Examine these resource objects links.

For example, the minimal describe for a service with a Department resource returns the following objects:

{
  "Resources" : {
    "Department" : {
      Department,
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/describe",
        "name" : "self",
        "kind" : "describe"
      } ]
    },
      ...
  }
}

By default children resources are not included in the minimal describe. Use the includeChildren query parameter to retrieve the minimal catalog describe with all available children resources nested within the parent resources. For example, to view children resources in the minimal describe, you can use a request like the following:

<base_url>/describe?metadataMode=minimal&includeChildren=true

The minimal describe with the includeChildren query parameter set to true for a Department resource that includes a child resource Employee returns the following objects:

{
  "Resources" : {
    "Department" : {
      Department,
     "children" :  {
          "Employee" :  {
            "links" : [ {
              "rel" : "self", 
              "href" : "<base_url>/Department/{id}/child/Employee/describe", 
              "name" : "self", 
              "kind" : "describe"
            } ]
         }
       },
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/describe",
        "name" : "self",
        "kind" : "describe"
      } ]
    },
      ...
  }
}

The following sample retrieves a minimal resource catalog describe, including children resources, where the Employee resource is nested within the Department resource.

Request

URL

<base_url>/describe?metadataMode=minimal&includeChildren=true
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload

{
  "Resources" :  {
    "Department" :  {
       "children" :  {
         "Employee" :  {
            "links" : [
            {
              "rel" : "self", 
              "href" : "<base_url>/Department/{id}/child/Employee/describe", 
              "name" : "self", 
              "kind" : "describe"
            } ]
        }
      },
       "links" : [
        {
          "rel" : "self", 
          "href" : "<base_url>/Department/describe", 
          "name" : "self", 
          "kind" : "describe"
        }
      ]
    }
  }
}

Retrieving a Resource Describe

REST APIs support retrieving a describe for a single resource, all the available resources, or only the nested resources. The describe returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition.

The describe for the resource allows you to identify the shape and actions allowed on the business object. It returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition.

The Oracle Business Object REST API framework supports the following describe use cases for the service end point:

Describe a single resource collection.
Describe a nested resource in a parent-child relationship.
Describe two or more named resource collections.
Describe all available resources (resource catalog). For details, see About the REST API Catalog Describe.

To retrieve the describe, invoke an HTTP GET with /describe appended to the resource URL.

For example, the following URL returns the describe for the Department resource:

<base_url>/Department/describe

Describing a Resource Collection

REST APIs support describing resource collections.

To examine a resource collection:

Execute the resource collection describe and locate the names of the resources in the describe.
Examine these resource objects to understand the shape of each resource:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies links and available actions (including media types).
- item specifies the shape of the items of the collection and itself specifies links and available actions.
- children specifies any nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the Department resource returns the following objects:

{
  "Resources" : {
    "Department" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Employee"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following sample describes the Department resource.

Request

URL

<base_url>/Department/describe
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload

{
  "Resources" : {
    "Department" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "DepartmentId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 4
      }, {
        "name" : "DepartmentName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 30
      }, {
        "name" : "RelState",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true
      } ],
      "collection" : {
        "rangeSize" : 25,
        } ],
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department",
          "name" : "self",
          "kind" : "collection"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
        }, {
          "name" : "create",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "testImpl",
          "parameters" : [ {
            "name" : "testid",
            "type" : "string",
            "mandatory" : false
          } ],
          "resultType" : "string",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.action+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
        } ]
      },
      "item" : {
        "links" : [ {
          "rel" : "child",
          "href" : "<base_url>/Department/{id}/child/Employee",
          "name" : "Employee",
          "kind" : "collection",
          "cardinality" : {
            "value" : "1 to *",
            "sourceAttributes" : "DepartmentId",
            "destinationAttributes" : "DepartmentId"
          }
        }, {
          "rel" : "self",
          "href" : "<base_url>/Department/{id}",
          "name" : "self",
          "kind" : "item"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "update",
          "method" : "PATCH",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "delete",
          "method" : "DELETE"
        } ]
      },
      "children" : {
        "Employee" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          }, {
            "name" : "FirstName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          }, {
            "name" : "LastName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "Email",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "JobId",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 10,
            "controlType" : "choice",
            "maxLength" : "10"
          }, {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "Salary",
            "type" : "number",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 8,
            "scale" : 2
          } ],
          "collection" : {
            "rangeSize" : 0,
            }, {
              "name" : "PrimaryKey",
              "attributes" : [ {
                "name" : "EmployeeId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 6
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "<base_url>/Department/{id}/child/Employee",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
            }, {
              "name" : "create",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            } ]
          },
          "item" : {
            "links" : [ {
              "rel" : "self",
              "href" : "<base_url>/Department/{id}/child/Employee/{id}",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "parent",
              "href" : "<base_url>/Department/{id}",
              "name" : "parent",
              "kind" : "item"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "multiplySalary",
              "parameters" : [ {
                "name" : "multiplicand",
                "type" : "number",
                "mandatory" : false
              } ],
              "resultType" : "number",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "links" : [ {
            "rel" : "self",
            "href" : "<base_url>/Department/{id}/child/Employee/describe",
            "name" : "self",
            "kind" : "describe"
          } ]
        }
      },
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/describe",
        "name" : "self",
        "kind" : "describe"
      } ]
    }
  }
}

Describing a Nested Resource

REST APIs support describing a nested resource that results from related business objects.

To examine nested resources in the resource catalog:

Execute the nested resource describe and locate the names of the resources in the describe. The children attribute identifies nested resources.
Examine these resource objects to understand the shape of each resource:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies links and available actions (including media types).
- item specifies the shape of the items of the collection and itself specifies links and available actions.
- children specifies the nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the nested resources Department and Employee returns the following objects:

{
  "Resources" : {
    "Employee" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Department"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following sample (URL1) describes the Employee resource which can be found in the context of a Department resource item.

Note: To recursively include all children of the resource item on the requested describe, provide the query parameter ?includeChildren=true on the describe URL.

Requests

URL 1

<base_url>/Department/10/child/Employee/describe
HTTP Method

GET
Content-Type

none
Payload

none

Responses

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload 1

{
  "Resources" : {
    "Employee" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "EmployeeId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 6
      }, {
        "name" : "FirstName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 20
      }, {
        "name" : "LastName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "Email",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "JobId",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 10,
        "controlType" : "choice",
        "maxLength" : "10"
      }, {
        "name" : "DepartmentId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 4
      }, {
        "name" : "Salary",
        "type" : "number",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 8,
        "scale" : 2
      } ],
      "collection" : {
        "rangeSize" : 25,
        }, {
          "name" : "PrimaryKey",
          "attributes" : [ {
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          } ]
        } ],
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department/10/child/Employee",
          "name" : "self",
          "kind" : "collection"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
        }, {
          "name" : "create",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        } ]
      },
      "item" : {
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department/10/child/Employee/{id}",
          "name" : "self",
          "kind" : "item"
        }, {
          "rel" : "parent",
          "href" : "<base_url>/Department/10",
          "name" : "parent",
          "kind" : "item"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "update",
          "method" : "PATCH",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "delete",
          "method" : "DELETE"
        }, {
          "name" : "multiplySalary",
          "parameters" : [ {
            "name" : "multiplicand",
            "type" : "number",
            "mandatory" : false
          } ],
          "resultType" : "number",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.action+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
        } ]
      },
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/10/child/Employee/describe",
        "name" : "self",
        "kind" : "describe"
      } ]
    }
  }
}