3.1 REST API

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

3.1Design DiscussionsREST API

This page represents on-going design of the 3.1 Repository Public RESTful API for use by any client. As each service is implemented and formally described it becomes self-documenting allowing for the generation of the published reference documentation (which will also be available from an installed Alfresco Repository).

The 3.1 RESTful API interface includes all functionality available in the 3.0 REST API interface

Alfresco REST Design Guidelines

Deployment REST API

Table of Contents

• 1 WCM Services
  
  
  
  • 1.1 Web Project Service
    
    
    
    • 1.1.1 webprojects
    
    
    • 1.1.2 webproject
    
    
  
  
  • 1.2 Web Project Membership
  
  
  • 1.3 Sandboxes
    
    
    
    • 1.3.1 List
    
    
    • 1.3.2 Get
    
    
    • 1.3.3 Create
    
    
    • 1.3.4 Submit
      
      
      
      • 1.3.4.1 All
      
      
      • 1.3.4.2 Partial
      
      
    
    
    • 1.3.5 Delete
    
    
    • 1.3.6 Modified
    
    
  
  
  • 1.4 Assets
    
    
    
    • 1.4.1 Sample JSON Data
      
      
      
      • 1.4.1.1 List
      
      
    
    
    • 1.4.2 Get
      
      
      
      • 1.4.2.1 Add
      
      
      • 1.4.2.2 Bulk import
      
      
    
    
  
  


• 2 Dictionary Services
  
  
  
  • 2.1 Public and Private Model Definition
  
  
  • 2.2 Data
    
    
    
    • 2.2.1 DictionaryMap
    
    
    • 2.2.2 Class
    
    
    • 2.2.3 Property
    
    
    • 2.2.4 Association
    
    
  
  
  • 2.3 Resources
    
    
    
    • 2.3.1 Classes Collection
    
    
    • 2.3.2 Class
    
    
    • 2.3.3 Sub Class Collection
    
    
    • 2.3.4 Properties Collection
    
    
    • 2.3.5 Property
    
    
    • 2.3.6 Association Collection
    
    
    • 2.3.7 Association
    
    
  
  

WCM Services

The scope of WCM Services Layer is heavily driven by the requirements of the preview release of Alfresco Web Studio.

Web Project Service

webprojects

Represents a collection of web projects

3.1_JavaScript_API

List all web projects in JSON format
Parameters:

• userName - optional parameter to restrict list of web projects to those which have the user as a member.   If omitted then return all web projects.
  

GET /alfresco/service/api/wcm/webprojects
=> WCMProject[]

GET /alfresco/service/api/wcm/webprojects?userName=fred
=> WCMProject[]

Sample JSON data

{
  data:[
{
   'url' : '\/alfresco\/service\/api\/wcm\/webprojects\/buffy',
   'webprojectref' : 'buffy',
   'name' : 'buffy',
   'title' : 'Buffy',
   'description' : 'Site dedicated to buffy the vampire slayer',
   'nodeRef' : 'workspace:\/\/SpacesStore\/dd7fc426-2367-4478-93fe-94444b37dfca',
   'isTemplate' : false
} ,
{
   'webprojectref' : 'smash',
   'name' : 'smash',
   'title' : 'smash',
   'description' : 'smash',
   'url' : '\/alfresco\/service\/api\/wcm\/webproject\/smash'
   'nodeRef' : 'workspace:\/\/SpacesStore\/dd7fc426-2367-4478-93fe-94444b37dfcc',
   'isTemplate' : false

}
  
 ]
}

webproject

Create a new web project

• name
  
• title
  
• dnsname
  
• description
  
• isTemplate
  
• nodeRef
  

POST /alfresco/service/api/wcm/webprojects
=> WCMProject

Get a a single web project in JSON format

GET /alfresco/service/api/wcm/webprojects/{WebProjectRef}

Update a web project

PUT /alfresco/service/api/wcm/webprojects/{WebProjectRef}
=> WCMProject

Delete a web project

DELETE /alfresco/service/api/wcm/webprojects/{projectref}

Web Project Membership

list all users who have a role in the the specified wcm web project

GET /alfresco/service/api/wcm/webprojects/{projectref}/memberships
=> WCMUser[]

add/invite an existing user to a web project with the specified role.

Sample JSON data

[
      {
         'role' : 'ContentManager',
         'person':
         {
            'userName' : 'admin',
            'firstName' : 'Administrator',
            'lastName' : '',
            'url' : '\/alfresco\/service\/api\/people\/admin'
         },
         'url' : '\/alfresco\/service\/api\/wcm\/webproject\/smash\/membership\/admin'
      }
    
]

POST /alfresco/service/api/wcm/webprojects/{projectref}/memberships
=> WCMUser/Role

Update a user's role - Not implemented - future

PUT /alfresco/service/api/wcm/webprojects/{projectref}/memberships/{userid}
=> WCMUser

Remove a user from a web project - deletes any resources they may have including unsubmitted items in their sandboxes.

DELETE /alfresco/service/api/wcm/webprojects/{projectref}/membership/{userid}
=> WCMUser

Sandboxes

List

List all sandboxes for the specified wcm web project reference (projectref) :

REQUEST:

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes

RESULTS (JSON):

{
  'data':[
  {
     'name' : 'fred's sandbox',
     'sandboxref' : 'fred',
     'url' : '\/alfresco\/service\/api\/wcm\/webprojects\/{projectref}\/sandboxes\/fred'

  }
    ,
  {
     'name' : 'stage',
     'sandboxref' : 'stage',
     'url' : '\/alfresco\/service\/api\/wcm\/webprojects\/{projectref}\/sandboxes\/stage'
  }]
}

An optional parameters 'userName' will restrict the list of the returned sandboxes
to those available to the specific user.

REQUEST:

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes?userName=fred

RESULTS (JSON):

  {
    'data':[
        {
           'name' : 'fred's sandbox',
           'sandboxref' : 'fred',
           'url' : '\/alfresco\/service\/api\/wcm\/webprojects\/{projectref}\/sandboxes\/fred'

        }
    ]
  }

When the user does not exist an empty JSON data set is returned:

  {
    'data':[]
  }

Get

Get the details about a specific sandbox.

REQUEST:

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}

RESULTS (JSON):

  {
    'data':
        {
           'name' : 'fred's sandbox',
           'sandboxref' : 'fred',
           'url' : '\/alfresco\/service\/api\/wcm\/webprojects\/{projectref}\/sandboxes\/fred'

        }
  }

Note that the JSON response is not an array of sandbox details.

Create

Create a new sandbox, if the sandbox already exists does nothing.

POST /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes

• NOTE: What is sent in the body to create the new sandbox?
  

Submit

Submits the content currently in the sandbox

All

POST /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/submitter

headers: 'Content-Type':'application/json'

'payload'AYLOAD

Example Payload (JSON)

  { 
    'label':'Submit Label',
    'comment':'Submit Comment',
    'all': 'true/false' 
  }

Partial

POST /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/submitter

• NOTE: What is specified in the payload to make it partially submit a sandbox?
  

Delete

Delete the specified sandbox, any contents are deleted. 
Will need to be the owner or a content manager to use this method.

DELETE /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}

Modified

Return a list of modified items within the sandbox.

New folders with content in them will only return the name of the folder and not
any of the content contained in the new folder;  'collapsed' as per existing WCM behaviour.

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/modified

Assets

Sample JSON Data

         'path' :    

List

Get the updated item details which are contained within this sandbox.
The result set is paged in order to handle potentially large result sets.

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/assets?size={pagesize}&pos={pageposition}

Get

Information about the specific asset

GET /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/assets/{assetref}

Add

Add asset to sandbox.

POST /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/assets

• NOTE: What is the payload for submitting an assets or asset to the sandbox
  

Bulk import

POST /alfresco/service/api/wcm/webprojects/{projectref}/sandboxes/{sandboxref}/assets

Dictionary Services

The Dictionary services provides read-only access to the elements of the Alfresco content model, including types and aspects and their properties and associations.

Public and Private Model Definition

TODO. The model needs to be extended to allow public and private model definitions. This should allow applications to interrogate the model to discover model elements (types and aspects) that are considered public i.e. creatable by end users as opposed to internal model definitions that are used by the core repository services and to support application features.

Data

DictionaryMap

A map of classes, associations or properties indexed by their name.

Example JSON:

{
   'cm:content' :
   {
      ... output class/association/property details here ...
   },
   'cm:versionable' :
  {
     ... output class/association/property details here ...
  }
}

Class

The Class data represents an Alfresco content model type or aspect and contains the following data:

• name - qualified name of the type
  
• isAspect - indicates whether this is an aspect or not
  
• title - title of the type
  
• description - description of the type
  
• parent - parent type, empty if no parent
  
• defaultValue - map of property names and the partial property objects
  
• defaultAspects - map of aspect names and the partial aspect objects
  
• properties - list of partial properties details
  
• associations - list of partial association details
  
• childAssociations - list of partial child association details
  
• url - resource URL to self
  

Example JSON:

{
   'name' : 'custom:myobject',
   'isAspect' : false,
   'title' : 'The Title',
   'description' : 'The Description',
   'parent' : 
   {      
      'name' : 'cm:object',
      'title' : 'Object',
      'url' : '/api/classes/cm_object'
   },
   'defaultValues' :
   {
      'custom:percentComplete' : 
      {
         'name' : 'custom:percentComplete',
         'defaultValue' : '10',
         'url' : '/api/classes/custom_myobject/properties/custom_percentComplete'
      },
      'custom:duration' : 
      {
         'name' : 'custom:duration',
         'defaultValue' : '120',
         'url' : '/api/classes/custom_myobject/properties/custom_duration'
      }
   },
   'defalutAspects' :
   {
      'cm:versionable' : 
      {
         'name' : 'cm:versionable',
         'title' : 'Versionable',
         'url' : '/api/classes/cm_versionable'
      }
   },
   'properties' : 
   {
      'cm:name' : 
      {
         'name' : 'cm:name',
         'title' : 'Name',
         'url' : '/api/classes/custom_myobject/properties/cm_name'
      },
      ....
   }
   'associations' :
   {
      'cm:translation' : 
      {
         'name' : 'cm:translation',
         'title' : 'Translation',
         'url' : '/api/classes/custom_myobject/associations/cm_translation'
      },
      ....
   },
   url: '/api/classes/custom_myobject'
}

Property

The Property data contains information about an Alfresco types property and contains the following data:

• name - property name
  
• title - property title
  
• description - description of the property
  
• defaultValue - default value, not present if none
  
• dataType - datatype of the property
  
• multiValued - multi value flag
  
• protected - protected property flag
  
• constraints - list of constraints that apply to the property, not present if none
  
• url - url to property resource
  

Example JSON:

{
   'name' : 'cm:name',
   'title' : 'Name',
   'description' : 'The name of the node',
   'defaultValue' : '',
   'dataType' : 'd:text',
   'multiValued' : 'true',
   'mandatory': 'true',
   'enforced' : 'true',
   'protected' : 'false',
   'indexed' : 'true',
   'indexedAtomically' : 'true',
   'constraints' :   
   [
      {
         'name' : 'REGEX',
         'params':
         {
            'pattern' : '....'         
         }
      },
      ...    
   ],
   'url' : '/api/classes/cm_object/properties/cm_name'
}

Association

The Association data represents an Alfresco either a child or general association between content types and contains the following data:

• name - child association name
  
• isChildAssociation - indicates whether the association is a child or general association
  
• title - child association title
  
• description - child description of the association
  
• protected - protected flag
  
• source.type - qualified source child association type
  
• source.role - source child association role
  
• source.mandatory - source mandatory flag
  
• source.many - source mandatory flag
  
• target.type - qualified target child association type
  
• target.role - target child association role
  
• target.mandatory - target mandatory flag
  
• target.many - target mandatory flag
  
• requiredChildName - required child association name, not present if none  (only present for child associations)
  
• duplicateChildNamesAllowed - duplicate child names flag  (only present for child associations)
  
• url - url to self
  

{
   'name' : 'cm:translation',
   'isChildAssociation' :  true,
   'title' : 'Translation',
   'description' : 'A translated version of the node',
   'protected' : false,
   'source':
   {
      'type' : '<url for type>',
      'role' : 'original',
      'mandatory': true,
      'many': true
   },
   'target':
   {
      'type' : '<url for type>',
      'role' : 'translation',
      'mandatory': true,
      'many': true,
   }.
   'requiredChildName' : '',
   'duplicateChildNameAllowed' : false,
   'url' : '/api/classes/cm_content/childassociations/cm_transation'
}

Resources

Classes Collection

Get a list of all the available classes (types and aspects) in the dictionary.  This list can optionally be filtered by model namespace prefix and/or name.  The list can also be filtered to return either only types or aspects.

Parameters:

• cf - indicates whether the returned list of classes should contain both aspects and types or just aspects of types.  Allowable values 'all', 'aspect' or 'type'.  If none specified 'all' is the default.
  
• nsp - namespace prefix filter
  
• n - class name filter
  

GET /api/classes
      ?cf={classFilter?}&nsp={namespacePrefix?}&n={name?}
      

Class

Get the details of a class (a type or aspect)

Note: class-name should include prefix, although use '_' instead of ':'. For example, use 'cm_content' instead of 'cm:content'

GET /api/classes/{class-name}
      

Sub Class Collection

Gets a list of a classes sub-classes.  This list can optionally be filtered by model namespace prefix and/or name.  The list can also be filtered to return either only types or aspects.  The recursive parameter indicates whether the results contain just the immediate children or all children.    

Parameters:

• r - true => all sub-type descendants, false => immediate sub-type children
  
• cf - indicates whether the returned list of classes should contain both aspects and types or just aspects of types.  Allowable values 'all', 'aspect' or 'type'.  If none specified 'all' is the default.
  
• nsp - namespace prefix filter
  
• n - class name filter
  

GET /api/classes/{class-name}/sub-classes
      ?r={recursive?}&cf={classFilter?}&nsp={namespacePrefix?}&n={name?}
      

Properties Collection

Get a list of the property definitions for a class.

Parameters:

• nsp - association namespace prefix filter
  
• n - association name filter
  

GET /api/classes/{class-name}/properties
      ?nsp={namespacePrefix?}&n={name?}
      

Property

Get a property definition.

GET /api/classes/{class-name}/propeties/{prop-name}
   

Association Collection

Get a list of the association definitions for a class.

Parameters:

• af - indicates whether the returned list of associations should contain both general and child associations or just one of the two.  Allowable values 'all', 'general' or 'child'.  If none specified 'all' is the default.
  
• nsp - association namespace prefix filter
  
• n - association name filter
  

GET /api/classes/{class-name}/associations
   ?af={associationFilter?}&nsp={namespacePrefix?}&n={name?}
   

Association

Get an association definition.

GET /api/classes/{class-name}/associations/{assoc-name}