X

The Digital Experience Platform blog covers the latest in innovative technologies to help you transform your business.

REST API Now Supports Metadata in DOCS

Kellsey Ruppel
Principal Product Marketing Director

Author: Victor Owuor, Senior Director, Oracle

It is our goal that Oracle Documents Cloud Service (DOCS) should be a platform for easily building cloud applications.   To make that possible, we provide a framework for embedding the DOCS user experience within your application.   We also offer a REST API for making calls to DOCS, allowing you to surface its capability within your user interface.  We are proud to announce that the REST API now supports metadata.

We will describe metadata with reference to an application for managing assets for a real estate listing site.   The application will manage the relevant assets within DOCS and surface those assets in UI that it will render separately.   As you would imagine, the application will need to store various images of the properties listed in the application.   For example, there may be a front picture and pictures of various rooms.  Additionally, there will be a need to track additional descriptive information about the assets.  It is that additional descriptive information that we refer to as metadata.  

The application might need to track an address for each property.  The address comprises a collection of:
  • A street address
  • A city
  • A state
  • A country
Each of those is referred to as a metadata field in DOCS.  The related fields are grouped in a metadata collection.  The application will define multiple collections and each folder or document could be associated with several collections.  For example, in additional to the address collection, properties on sale might also be associated with a forsale collection, including the following fields:
  • A sale price
  • Property taxes
  • Previous sale prices
In contrast, properties for a rental property would instead be associated with a for-rent collection, including the following fields:
  • Rental price
  • Lease term
DOCS allows an administrator to easily define metadata collections and the fields in it.   In the example above, an administrator would define the address collection as follows:
POST …/metadata/Address?fields=Street,City,State

He can trivially alter the address collection to include a country as follows:

PUT …/metadata/Address?addFields=Country

Once a collection and its fields are defined, any user can assign it to a folder or a document.  The calls for doing so are as follows:

POST …/folders/{folder id}/metadata/Address
POST …/files/{file id}/metadata/Address

 Of course, only users with contributor access to the folder or document may assign a collection.

Having assigned the collection, users may set values for the various fields in the collection as follows: 

POST …/folders/{folder id}/metadata?collection=Address&Zip=55347&City=Minneapolis
POST …/files/{file id}/metadata?collection=Address&Zip=55347&City=Minneapolis

Collections and values assigned to a folder are inherited by both its sub-folders and any documents within it.  The inherited value can be overridden by assigning a specific value for the metadata field to an item.

 All of the metadata properties would be of little value if you could not retrieve metadata values previously assigned to a document.   We allow you to do that in a simple call that is formatted as follows:

GET …/folders/{folder id}/metadata
GET …/files/{file id}/metadata

That call returns the metadata values in a JSON object that is contained within the HTTP response.  A sample response is shown below:

Additional information about the metadata feature is available here.


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.