Loading ...

OpenWGA 7.10 - OpenWGA Concepts and Features

Design and development » REST web service

Working with documents in REST

Just like collections do documents represented on the REST service always have the same structure:

{

  • ...
  • "key":{
    • "type":"documentType",
    • ...
    },
  • "resource":{
    • "type":"documentType",
    • "items":{
      • "listType":"json",
      • "stringItem":{
        • "string":"Blockbuster On Demand® movies and music downloads with connected music player\nWater-resistant and dustproof"
        },
      • "stringListItem":{
        • "strings":{
          • "values":[
            • "Value1",
            • "Value2",
            • "Value3"
            ]
          }
        },
      • "booleanItem":{
        • "bool":false
        },
      • "numberItem":{
        • "number":12345.0
      • },
      • "dateItem":{
        • "date":"ISO8601DateLiteral"
      • },

      • ...
        • },
    • "metaData":{

      • "listType":"json",
      • "stringMeta":{
        • "string":"The value"
        },
      • ...
    • },
      • "relations":{
        • "listType":"json",
        • "targetbuild":{
          • "href":"Target-URI",
          • "protected":true
          }
        }
    • },
    • "refs":{
      • ...
    • },
    • "timestamps":{
      • "created":"ISO8601DateLiteral",
      • "lastModified":"ISO8601DateLiteral"
      • ...
    • }
    }

    Some explanations of the additional properties on the envelope object:

    • The key property contains OpenWGA key information for the resource, depending on the document type represented
    • The timestamps property contains timestamps about the document, also depending on the document type represented

    The important payload of the resource is of course inside the resource property. Here we have the following properties:

    • The property items contains an object with item data, keyed by the item name. This is only the case for documents which actually contain items.
    • The property metaData contains an object with data of metadata fields, keyed by the field name.
    • The property relations contains an object with relation data, keyed by the relation name. This is only the case for content documents which actually contain relations. Relations groups are not contained here but retrievable via subcollection, differing by API.

    Data Fields

    Metadata fields and items are regarded data fields on document resources and the objects that represent them share a common structure as REST objects. This structure is dependent on the data type of the value.

    Data type Structure
    List of booleans "fieldName":{ "bools":{ values:[true,false,true] } }
    List of dates "fieldName":{ "dates":{ values:["2013-11-08T17:01:43Z","2014-03-01T15:42:12Z","2014-01-01T09:35:12Z"] } }
    List of numbers "fieldName":{ "numbers":{ values:[1,2,3] } }
    List of strings "fieldName":{ "strings":{ values:["a","b","c"] } }
    Single boolean "fieldName":{ "bool":true }
    Single date "fieldName":{ "date":"2013-11-08T17:01:43Z" }
    Single number "fieldName":{ "number":1234.0 }
    Single string "fieldName":{ "string":"fieldValue" }

    For dates the OpenWGA REST client generally produces and consumes string literals in ISO8601 format, representing the UTC time.

    Creating and updating documents

    To create or update documents you essentially just put/post the document object - the part of the envelope under property "resource" - to the appropriate URL using the appropriate HTTP method. URL and method are different depending on the API and the document used (see API documentation for details), however the posted/put data is always interpreted the same:

    Everywhere a JSON object is used to represent collections you can either post/put back the whole object or just the part that you want updated. For example: When updating a single item it is sufficient to only post back that item property unter "items":

    {

    • "type":"documentType",
    • "items":{
      • "listType":"json",
      • "stringItem":{
        • "string":"This is updated"
      • }
    • }
    }

    The properties that are omitted will stay untouched on the update (if any existed). If you actually want to delete something here you need to post the respective object - an item for example : with property "delete:true":

    {

    • "type":"documentType",
    • "items":{
      • "listType":"json",
      • "stringItem":{
        • delete:true
      • }
    • }
    }

    Everywhere a JSON array is used to represent collections you must post the whole collection as you want it to be stored. Omitted elements, that were part of the array before, will be removed from the collection. In other words:The updated array collection exactly represents what you posted. For example: String list items:

    {

    • "type":"documentType",
    • "items":{
      • "listType":"json",
      • "stringListItem":{
        • "strings: {
          • values:["a","b"]
        • }
      • }
    • }
    }

    Assuming that item "stringListItem" previously contained ["a","b","c"] it will only contain ["a","b"] after putting this.

    Updating metadata applies to the same rules as updating metadata in normal content management. There are some metadata fields that are not writable (like CREATED, LASTMODIFIED, VERSION, WORKFLOW_HISTORY). When these metadata fields are sent on PUT/POST requests they are ignored.

    Enhancing output

    Via enhancing you can modify the output of the resource to either reduce or add output data.

    You can enhance metadata to control what metadata fields are put out. Normally the set that is put out is a reduced set of metadata that makes sense in most usages of rest. You can either control which set is put out or explicitly add single metadata fields to the chosen set. This is done via URL parameters:

    • metaSet=none|standard|all - Controls the basic set that is put out. "none" obviously means none, "default" is the default reduced set, "all" contains really all metadata fields of the document
    • meta=metaName - Manually adds a metadata field to the output that is not contained in the chosen set. Can be used multiple times with differing metadata field names. Having one such parameter changes the metadata set to "none", unless this is explicitly chosen via parameter "metaSet".

    The same way you can enhance items on content documents and user profiles with URL parameters:

    • itemSet=none|standard|all - Controls the basic set that is put out. "none" obviously means none, "default" is the default reduced set which differs by REST API (is actually unrestricted on "CMS" and "Query", is restricted on "HDBModel" to the declared items in the model), "all" contains really all items of the document
    • item=itemName - Manually adds an item to the output that is not contained in the chosen set. Can be used multiple times with differing item names. Having one such parameter changes the item set to "none", unless this is explicitly chosen via parameter "itemSet".

    The same is also true for enhancing relations  on content documents using these URL parameters:

    • relationSet=none|standard|all - Controls the basic set that is put out. "none" obviously means none, "default" is the default reduced set which differs by REST API (is actually unrestricted on "CMS" and "Query", is restricted on "HDBModel" to the declared relations in the model), "all" contains really all relations of the document.
    • relation=relationName - Manually adds a relation to the output that is not contained in the chosen set. Can be used multiple times with differing relation names. Having one such parameter changes the metadata set to "none", unless this is explicitly chosen via parameter "relationSet".

    On a resource you can also enhance the references that are put out under property "refs" of the envelope. If they point to collections they normally only put out the URI of this collection. However you can influence certain references to directly contain the (first page of the) collection using URL parameter:

    • ref=referenceName - Instructs the reference of the given key to directly include the (first page of the) collection it adresses. Can be used multiple times with differing reference names.

    Custom resource enhancers

    These are TMLScript functions that are called with the current resource as parameter. They may add custom items and metadata fields to the resource that they generate by arbitrary functionalities.

    To create a custom enhancer:

    • Create a TMLScript module in your design on path "scripts/tmlscript/wga/rest/resource-enhancers.tmlscript"
    • The contents of this module is a Custom TMLScript object of which every method is a separate custom resource enhancer. The name of the enhancer is the method name.
    • Each method receives two parameters:
      • A RESTReference object representing the resource that is to be added to the collection
      • The WGAPI object of the document resource that this resource points to. For example, a WGContent for content documents.
    • By using the methods on the RESTReference object the script can add custom items, metadata fields and relations to the reference to display.

    An example of a custom resource enhancer "special" which analyzes an "additionalfeatures" item and sets boolean items as result is printed below:

    this.special = function(res, doc) {

        var addFeatures = content().getItemValue("additionalfeatures");
        if (addFeatures != null && /NFC/.test(addFeatures)) {
            res.addItem("hasNFC", true);
        }
        else {
            res.addItem("hasNFC", false);
        }  

        if (addFeatures != null && /Flash/.test(addFeatures)) {
            res.addItem("hasFlash", true);
        }
        else {
            res.addItem("hasFlash", false);
        }

    }

    This enhancer could be used on any resource by adding it the URL parameter "enhancer=special".

    Reference types

    The "refs" property of envelopes for resources you will find references, keyed by their id, that are of differing type and are therefor used in varying ways. The types are identified by their property "reftype":

    reftype:"resource" - References to other resources:

    "area":{

    },

    These are simple point-to-point references from once resource to another. The "resourceType" identifies the type of target resource. There is just a single "href" pointing to the far resource.

    reftype:"collection" - References to collections:

    "childPages":{

    }

    This is a reference to a collection that is related to the current resource. Calling the "href" will bring up this collection.

    reftype:"lookup" - A lookup function

    "context":{

    }

    This is a function which can be used to lookup resources or collections via some key information. The "href" cannot be used directly but is only the root URI for the lookup function. See property "uriExtension" what needs to be added to the root URI in order to execute the lookup. Dynamic data is there identified as being in curly braces.

    The example above allows to specify a context expression as URL parameter and lookup a resource this way, in this case a content document. It could be used with the following example URL to resolve a content document with context expression "name:home":

    http://localhost:8080/services/rest/v1/dbs/site/cms/context?expression=name:home

    The URL will take you directly to the resolved resource.