Why you should stay clear of REST

Once again I get inspired by to write this blogpost by Alvaro de Andres Documentum 16.3 delayed until Feb 2018 blogpost – there is some “interesting discussion” about REST where you can find following opinion from another member of talented team:

Is DFS a personal target for your projects? Baseline REST is a mature offering and it has active Engineering working on it. The planet seems to be focused on a RESTful interface and the DCTM platform is meeting that focus with a set of platform APIs. As I’m sure you are aware Captiva, xCP and D2 can be access through REST interfaces.

Actually, it is not clear what Tomas meant under the word “REST” because my observations about REST are following:

  • when most people talk about REST they typically mean JSON, which is obviously wrong: it is true that in the most cases (especially when REST client is a web-browser) REST is used together with JSON, but if we want to get faster data processing or put validation rules on data nothing prevents us from using XML or protocol buffers. Moreover the idea to use JSON in most cases sounds ridiculous: we spend a lot of time on designing data structures, but once we chose to use JSON as serialisation technique we throw all our efforts out of window.
  • Documentum’s REST API is actually not REST-compliant, so when talking about Documentum under the REST we should mean “something that looks like REST”, so, yes, REST seems to be a standard of providing interoperability between computer systems on the Internet,
    but how it relates to Documentum?

Let’s discuss the second point: why is Documentum REST not REST-compliant? The base idea is following: when we work with our data through REST API we consider two types of resources: elements and collections of elements, which could be queried/modified using GET, PUT, POST, PATCH and DELETE methods, the behaviour of these methods is following:

Method Resource type Contract
Collection Element
GET List the URIs and perhaps other details of the collection’s members Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type readonly
PUT Replace the entire collection with another collection Replace the addressed member of the collection, or if it does not exist, create it idempotent
PATCH Not generally used Update the addressed member of the collection
POST Create a new entry in the collection. The new entry’s URI is assigned automatically and is usually returned by the operation Not generally used. Treat the addressed member as a collection in its own right and create a new entry within it
DELETE Delete the entire collection Delete the addressed member of the collection idempotent

Below are some explanations of the table provided above:

  • Documentum REST API should not allow to do something like:
    GET /dctm-rest/repositories/DOCBASE?dql=delete%20dm_user%20objects
    

    because GET method is readonly

  • PUT method against element must completely replace element’s data, i.e. if you are doing something like:
    PUT /dctm-rest/repositories/REPO/DOCBASE/dm_user/11bc614180000522
    Content-Type: application/vnd.emc.documentum+json;charset=UTF-8  
    
    properties: {
      "user_address": "user@domain.tld"
    }
    

    the request above should set user_address to user@domain.tld and clean other properties, if your objective is to update user’s email you should do something like:

    PATCH /dctm-rest/repositories/REPO/DOCBASE/dm_user/11bc614180000522
    Content-Type: application/vnd.emc.documentum+json;charset=UTF-8  
    
    properties: {
      "user_address": "user@domain.tld"
    }
    
  • example of POST method usage against element should look like:
    POST /dctm-rest/repositories/REPO/DOCBASE/dm_workflow/4dbc6141801aa1e1/attachments
    Content-Type: application/vnd.emc.documentum+json;charset=UTF-8  
    
    properties: {
      "object_name": "new attachment"
    }
    
    

Now, how it does look from Documentum perspective:

  • updating object:
    POST http://localhost:8080/acme-rest/repositories/REPO/alias-sets/6600000580000515 HTTP/1.1  
    Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==  
    Accept: application/vnd.emc.documentum+json  
    Content-Type: application/vnd.emc.documentum+json  
      
    {  
      "properties":{  
        "alias_name":["RestASX ", "Everyone_Write"],  
        "alias_value":["/Resources/Registry/Presets", "dce_world_write"],  
        "alias_category":[5, 6],  
        "alias_usr_category":[1, 1],  
        "alias_description":["A test alias set", "A second alias set"]  
      }  
    } 
    
    HTTP/1.1 200 OK  
    Content-Type: application/vnd.emc.documentum+json;charset=UTF-8  
    Content-Length: 725     
      
    {  
      "type":"dm_alias_set",  
      "definition":"http://localhost:8080/acme-rest/repositories/REPO/types/dm_alias_set",    
      "properties":{  
        "owner_name":"dmadmin",  
        "object_name":"TestASX",  
        "object_description":"A test alias set",  
        "alias_name":["RestASX ", "Everyone_Write"],  
        "alias_value":["/Resources/Registry/Presets", "dce_world_write"],  
        "alias_category":[5, 6],  
        "alias_usr_category":[1, 1],  
        "alias_description":["A test alias set", "A second alias set"]  
        "i_is_replica":false,  
        "i_vstamp":0,  
        "r_object_id":"6600000580000515"  
      },  
      "links":[  
        {"rel":"self","href":"http://localhost:8080/acme-rest/repositories/REPO/alias-sets/6600000580000515"},    
        {"rel":"author","href":"http://localhost:8080/acme-rest/repositories/REPO/users/dmadmin"}    
      ]  
    }  
    

    and inconsistencies are:

    • improper usage of POST method
    • PATCH method is not implemented at all
    • if under POST they actually mean PUT they should clean values of owner_name, object_name and object_description attributes – I believe talented team actually uses POST as a replacement of PATCH, though PATCH method was introduced in 2010 (7 years ago)
  • dealing with workflow tasks:
    PUT /rest-app-name/processes/process-system-name/process-id/task-name/task-id/status
    Content-Type: application/vnd.emc.documentum+json  
    
    {
      "acquire":{}
    }
    

    that is a total mess, the correct implementation should be:

    PATCH /rest-app-name/processes/process-system-name/process-id/task-name/task-id
    Content-Type: application/vnd.emc.documentum+json  
    
    properties: {
      "r_runtime_state": 1
    }
    

As you can see REST implementation in Documentum is actually not REST-compliant, so, I have no idea what talented team was doing last 8 years. On the other hand it is not a big issue in comparison with the next one. At current moment ECD/OT provides following options to work with Content Server:

and the problem is that all those options do not provide you an out of the box robust integration with Documentum: while the planet seems to be focused on ORM, DDD and scaffolding, Documentum developers write tons of boilerplate code.

Advertisements

2 thoughts on “Why you should stay clear of REST

  1. Pingback: Why you should stay clear of REST. Part II | Pro Documentum

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