3.1 REST API

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

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


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':PAYLOAD

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}
  

Attachments

    Outcomes