3.0 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.0Design DiscussionsActivities ServiceDraft PagesSite ServiceREST APIHTTP API

This page represents on-going design of the 3.0 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 scope of services is heavily driven by the requirements of the Alfresco 3.0 Web Client.

Alfresco REST Design Guidelines


Table of Contents


Node Service (TBD)


Data


Node



{
   'nodeRef' : 'workspace://SpacesStore/123-123-123',
   'url' : '/services/api/node/workspace/SpacesStore/123-123-123'
}

Site Service


Data


Site Details


Details of the site that include:


  • short name (this must be unique and always present)
  • site preset (mandatory for create)
  • title
  • description
  • indication of whether the site is public (made read only in version 3.2)
  • site visibility either public, private or moderated (introduced in version 3.2)
  • site node URL
  • tag scope URL for the site
  • site URL (provided when retrieving site details)



JSON example:



{
   'shortName' : 'shortName',
   'sitePreset' : 'sitePresetName',  
   'title' : 'title',
   'description' : 'description',
   'isPublic' : true,
   'visibility' : 'PUBLIC',
   'node' : '/services/api/node/workspace/SpacesStore/123-123-123-123',
   'tagScope' : '/services/api/tagscopes/workspace/SpacesStore/123-123-123-123'
   'url' : '/services/api/sites/shortname'
}

SiteQuery


Introduced in version 3.2

Contains site query details.  These relate to a property of the site and indicate how the values of the that property should be queried. 

Exact match queries on short name and exact matches on site short name that the current user is a member of are supported

JSON example:



{
   'shortname' :
   {
      'match' : 'exact',
      'values' :
      [
         'mySite',
         'mySite2'
      ]
   }      
}

and



{
   'shortname' :
   {
      'match' : 'exact-membership',
      'values' :
      [
         'someSite',
         'anotherSite'
      ]
   }      
}




MembershipDetails


Details of a site membership that includes:


  • role - the role that the person plays in the site
  • person - the person (see JSON defintion for person)
  • url - url to the membership resource



JSON example:



{
   'role' : 'SiteManager',
   'person' :
   {
      'userName' : 'userId',
      'url' : '/alfresco/service/api/people/userId',     
      'firstName' : 'Bob',
      'lastName' : 'Smith'
   },
   'url' : '/alfresco/service/api/sites/mySite/memberships/userId'       
}

Resources


Site Collection


The site collection contains a list of sites available across the repository.  This collection may be filtered.

Methods:


GET /sites 
      ?nf={namefilter}&spf={sitepresetfilter}
     

POST /sites 
      => SiteDetails
     

Site Collection Query


Introduced in version 3.2

A site collection query contains a list of sites that satisfy the query information posted to the resource.

Methods:


POST /sites 
      => SiteQuery
     

Site


The site resource represents the site.  This consists of a name, description and a list of memberships for that site.  There will also be information about the 'owner' of the site and whether the site is public of not.

Methods:


GET /sites/{shortname} 
     

PUT /sites/{shortname}      
      => SiteDetails

DELETE /sites/{shortname}

Site Membership Collection


The membership collection represents a list of all the membership details for a site.  This collection may be filtered.

Methods:


GET /sites/{shortname}/memberships 
      ?nf={namefilter}&rf={rolefilter}
     

POST /sites/{shortname}/memberships 
       => MembershipDetails

Site Membership


The site membership resource represents a users membership to a site.  This consists of a link to the site and the user concerned.  It also contains information about the 'role' or permissions that user has on that site.

Methods:


GET /sites/{shortname}/memberships/{username} 
     

PUT /sites/{shortname}/memberships/{username} 
   => MembershipDetails

DELETE /sites/{shortname}/memberships/{username}

Invite Service


NOTE - the API to this interface is subject to change - please use with care.

Note that throughout this section (and the code implementing it), the word 'invite' is used within the context of its informal usage as a noun - with the same meaning as 'invitation'.


Data


InviteInfo


Information pertaining to an invite:


  • Invite ID (this must be unique and always present)
  • User name of inviter (invite sender)
  • User name of invitee (invite recipient)
  • Site (the short name of the site that the inviter is inviting the invitee to join)
  • Invite URL (retrieves this InviteInfo instance)

Example of JSON representation of an InviteInfo object:



{
   'inviteId' : 'jbpm$98',
   'inviterUserName' : 'Bob.Lawrence',
   'inviteeUserName' : 'Tom.Richards',
   'siteShortName' : 'BobsBicycles',
   'inviteUrl' : '/api/invites?inviteId=jbpm$98'
}

Resources


Invite Collection


An invite collection contains a list of pending invites, filtered by the parameters provided.
Pending invites are those which haven't been cancelled by the inviter, or accepted or rejected by the invitee.

Methods:

Note that all the parameters for this method are optional, but at least one them must be provided



GET /invites?inviterUserName={inviterUserName}&inviteeUserName={inviteeUserName}&siteShortName={siteShortName}</url>
      returns InviteInfo[]

Invite


An invite resource represents an invite, the properties of which are outlined above in InviteInfo

Methods:


TODO: Note that the method below will probably in the future be superceded by something more RESTful like [GET /invites/{inviteId} returns InviteInfo]

GET /invites?inviteId={inviteId}
      returns InviteInfo



TODO: Note that the method below will probably in the future be superceded by something more RESTful like [POST /invites input InviteInfo] (though the problem with this is that I need to find some way of passing in the invitee's first name, last name and email address, which are not part of InviteInfo (and shouldn't be). Perhaps this can be achieved by the client first calling [PUT /people/{inviteeUserName} input PersonDetails], with the invitee's first name, last name, and email address included in the updated person details)



GET /invite/start?inviteeFirstName={inviteeFirstName}&inviteeLastName={inviteeLastName}&inviteeEmail={inviteeEmailAddress}&siteShortName={siteShortName}
      returns InviteInfo



TODO: Note that the method below will probably in the future be superceded by something more RESTful like [DELETE /invites/{inviteId} returns InviteInfo]



GET /invite/cancel?inviteId={inviteId}     
      returns InviteInfo



TODO: Note that below, the parameters {inviteeUserName} and {siteShortName} shall be removed soon as they are redundant, and the values thereof should actually be looked up by the Web Script itself (as they can be looked up by using the {inviteId} parameter)
Also note that the method below will probably in the future be superceded by something more RESTful like [PUT /invites/{inviteeUserName} input InviteDetails, and including the updated state of accepted in the InviteDetails. The problem with this however is that I don't know how to perform a PUT Web Script call from a URL within the body of the invite email]



GET /inviteresponse/accept?inviteId={inviteId}&inviteeUserName={inviteeUserName}&siteShortName={siteShortName}     
      returns InviteInfo



TODO: The same change notifications from the previous method apply here too.



GET /invite/inviteresponse/reject     
      returns InviteInfo?inviteId={inviteId}&inviteeUserName={inviteeUserName}&siteShortName={siteShortName}



Getting information about an invite if the id and ticket is known:



GET api/invite/{inviteId}/{inviteTicket}
  

Note: This call does not require authentication


Person Service


Data


PersonQuery


A person query contains parameters to be used when querying the repository for people:


  • part of name
  • part of organisation
  • part of email address

Person


Person data includes:


  • unique identifier
  • title
  • first name
  • last name
  • organisation
  • job title
  • email address
  • bio
  • avatar URL
  • sites - url to the collection of sites the user is an explicit member of

JSON example:



{
   'userName' : 'userId',
   'url' : '/alfresco/service/api/people/userId',     
   'firstName' : 'Bob',
   'lastName' : 'Smith',
   'sites' : '/alfresco/service/api/people/userId/sites'
}

Resources


People Query


A query collection containing people in the repository that match the query parameters.

Methods:


 GET /api/query/people => PersonQuery 

People Collection


The people collection contains a list of all the people in the repository.  This list may be filtered.

Methods:


 GET /api/people 

 POST /people 
=> Person

Person


The person resource represents an alfresco user.

Methods:


 GET /api/people/{userid} => Person 

 PUT /api/people/{userid} 

 DELETE /api/people/{userid} 

Persons Site Collection


A list of the sites that a person has an explicit memebership of.

Methods:


 GET /api/people/{userid}/sites 
  

Activities Service


Assumptions (TBC)


  • siteId (equivalent to site shortname) has a well-defined max length - note: activities service schema currently accommodates siteIds upto 255 characters
  • userId (equivalent to person username) has a well-defined max length - note: activities service schema currently accommodates userIds upto 255 characters

Data


Feed Control


Feed control data includes:


  • siteId    (site shortname)
  • appToolId (app/tool id)

Resources


User Feed


Get user feed entries for currently logged in user. Optionally filter by site. Required authentication = 'user'.

Methods:


GET /activities/feed/user

GET /activities/feed/user?s={siteId}

As currently logged in admin, get user feed entries for specified user. Optionally filter by site. Required authentication = 'admin'.

Methods:


GET /activities/feed/user/{userId}

GET /activities/feed/user/{userId}?s={siteId} 

Site Feed


Get site feed entries for a given site. If site is private then currently logged in user must be a member of the site or an admin (else will get 401). Required authentication = 'user'.

Methods:


GET /activities/feed/site/{siteId} 

User Feed Control


Get user feed controls for currently logged in user. Required authentication = 'user'.

Methods:


GET /activities/feed/controls 
     



Set user feed control for currently logged in user. Required authentication = 'user'.

Methods:


POST /activities/feed/control
      => FeedControl

Unset user feed control for currently logged in user, for given {siteId} or given {appToolId} or given combination (if both are supplied). Required authentication = 'user'.

Methods:


DELETE /activities/feed/control?s={siteId}&a={appToolId}

Rendition Service (TBD)


Data Dictionary Service (TBD)


  1. Read access to dictionary models

Properties Service (TBD)


  1. read/write of node
    1. properties
    2. assocs
    3. etc

Thumbnail Service


Data


Thumbnail Details


Contains the name of the thumbnail and the URL to the thumbnail content.  Only the thumbnail name is madatory, other data is present if appropriate.

JSON Example:



{
   'thumbnailName' : 'webpreview',
   'url' : '/alfresco/service/api/node/workspace/SpacesStore/43170404-5d87-4d90-8587-55113bf7ec4f/content/thumbnails/webpreview'
}

Resources


Thumbnail Collection


The collection of thumbnails for a given nodes content property.

Methods:


GET /node/{store_type}/{store_id}/{id}/content{property}/thumbnails 
     

POST /node/{store_type}/{store_id}/{id}/content{property}/thumbnails
      ?as={async?}     
      => ThumbnailDetails (only thumnbnail name is required)
     

Thumbnail


GET /node/{store_type}/{store_id}/{id}/content{property}/thumbnails/{thumbnailname} 
      ?c={queueforcecreate?}&ph={placeholder?}
     

The 'c' arg can have the value of 'force' to force the synchronous creation of the thumbnail immediately or 'queue' to asynchronously queue the creation of the thumbnail.


PUT /node/{store_type}/{store_id}/{id}/content{property}/thumbnails/{thumbnailname}
        ?as={async?}

PUT /path/{store_type}/{store_id}/{id}/content{property}/thumbnails/{thumbnailname}
        ?as={async?}

DELETE /node/{store_type}/{store_id}/{id}/content{property}/thumbnails/{thumbnailname} 

DELETE /path/{store_type}/{store_id}/{id}/content{property}/thumbnails/{thumbnailname}

Tagging Service


Data


Also see Node


Tag Scope



{
   'node' : 'workspace://SpacesStore/123-123-123'.
   'lastupdated' : { ... date ... },
   'tags' : '/../../tags'
}

Tag Map



{
   'tagName1' : 12,
   'tagName2' : 10,
   'tagName3' : 2,
}

Resources


Tag Collection



GET /api/tags/{store_type}/{store_id}
   ?tf={tag_filter?}
  


GET /api/tags/{store_type}/{store_id}/{tag}/nodes
  

GET /api/tags/{store_type}/{store_id}/{id}/{tag}/nodes 
  

Node Tag Collection


GET /api/node/{store_type}/{store_id}/{id}/tags 
  

POST /api/node/{store_type}/{store_id}/{id}/tags 
   => String[]
  

Tag Scope


TODO: The node specific urls should probably use /api/tagscopes/node/... instead of /api/tagscopes/...



POST /api/tagscopes
   => Node


GET /api/tagscopes/{store_type}/{store_id}/{id}
  


DELETE /api/tagscopes/{store_type}/{store_id}/{id}


GET /api/tagscopes/{store_type}/{store_id}/{id}/tags
   ?tn={topN}
  

Preferences Service


Data


Preference Set



{
   'alfresco' :
   {
      'myComponent' :
      {
         'StringPref' : 'myPrefValue',
         'BooleanPref' : true
      },
      'myOtherComponent' :
      {
         'NumberPref' : 12
      }
   },
   'myPrefWithNoNamespace' : 'someValue'
}

Resources


Users Preference Set



GET /api/people/{userid}/preferences
   ?pf={preferencefilter?}
  

Gets all the preferences set for user.  All preference values are returned in a preference set. 

The name filter can be used to restrict the set of returned preferences.  It can be a partial name, specifying part of the preferences namespace. (eg: ?pf=alfresco.myComponent will return just preference values for alfresco.myComponent)  The full preference name can be specified to return only one preference value.



POST /api/people/{userid}/preferences
   => PreferenceSet


DELETE /api/people/{userid}/preferences
   ?pf={preferencefilter?}

Discussion Service


Provides methods to fetch, create and update forum posts. Posts are hierarchical, a post can be created as a reply to another post.




Data objects


=> Forum



{
   'name' : 'name',
}





{
   'nodeRef' : '<nodeRef>',
   'postsURI' : 'URI to fetch the posts',
   'name' : 'myForum',
}



=> Post



{
   'title' : 'title',
   'content' : 'content',
   'tags' : [ 'ECM', 'Alfresco' ]
}

Notes:
* '' or [] will be used for fields that are not specified
* tags sets the set of tags, replacing the old set of tags





{
   /* Top-level posts only data */
   'name' : '<name of the post>',
   'totalReplyCount' : 10,
   'lastReplyBy' : '<date>',    // only available if totalReplyCount > 0
   'lastReplyOn' : '<date>',    // only available if totalReplyCount > 0
   'tags' : [ 'Alfresco', 'ECM' ],

   /* Fields available for all posts */
   'url' : '/api/forum/post/node/{store_type}/{store_id}/{id}',
   'repliesUrl' : '/api/forum/post/node/{store_type}/{store_id}/{id}/replies',
   'nodeRef' : '<nodeRef>',
   'title' : '<title>',
   'createdOn' : '<date>',
   'modifiedOn' : '<date>',
   'author' : '<username>',
   'isUpdated' : true/false,
   'updatedOn' : '<date>', // only available if isUpdated==true
   'content' : '<content>',
   'replyCount' : 10,      // direct replies to this post
   'permissions' : [ 'edit': true, 'delete' : true, 'reply' : true ]
}

Notes:
* Only top-level posts support tagging for now
* Only top-level posts have totalRepliesCount, lastReplyOn, lastReplyBy fields
* In case there are no replies, lastReplyOn and lastReplyBy won't be returned
* The 'name' value of top-level posts can be used as part of the path in site/container/path urls to fetch the post





{
   /* Exactly the same information as in the post structure above */
   <post properties>

   /* If children are returned as well, they will be contained in following array */
   children: []
}




Methods


Use following methods to create and manage forums.

Fetch all forums in the system or forums located at a specific location



GET /api/forums
  



Get the forum details



GET /api/forum/node/{store_type}/{store_id}/{id}
  



Use following methods to manage forum posts:



Get all posts (optinally filtered by a tag):

GET /api/forum/node/{store_type}/{store_id}/{id}/posts?tag={tag}
  



Adding a new post to a forum:



POST /api/forum/node/{store_type}/{store_id}/{id}/posts   (maps to a topic/post in the forum model)
   => Post
  



Fetch the replies for a post:



GET /api/forum/post/node/{store_type}/{store_id}/{id}/replies?levels={levels}
  



Adding a reply to a post:



POST /api/forum/post/node/{store_type}/{store_id}/{id}/replies
   => Post
  



Get, update and delete a post (regardless whether it is a top-level post or a reply post):



GET /api/forum/post/node/{store_type}/{store_id}/{id}
  

Blogging Service


This API provides two kind of methods:

* Management of external blog configuration data as well as publishing/updating/unpublishing a post to it
* Management of blog posts (getting a list of posts in a space, creating, updating and deleting posts)

Data objects


=> ExternalBlogConfiguration



{
   'type' : '<blog type, currently either 'typepad' or 'wordpress'>',
   'id' : '<id of the blog>',
   'name' : '<blog name>',
   'description' : '<blog description>',
   'username' : '<username>',
   'password' : '<password>',
}





{
   'blogPostsUrl' : '/api/blog/node/{store_type}/{store_id}/{id}/posts',
   'type' : '<blog type, currently either 'typepad' or 'wordpress'>',
   'id' : '<id of the blog>',
   'name' : '<blog name>',
   'description' : '<blog description>',
   'url' : '<url to the external blog>',
   'username' : '<username>',
   'password' : '<password>',
}



=> BlogPost



{
   'draft' : false/true,
   'title' : 'title',
   'content' : 'content',
   'tags' : [ 'ECM', 'Alfresco' ]
}

Notes:
* Once a post change from draft to non-draft it cannot be changed back to draft
* If any of the other fields is not specified, a default value ('' or []) will be used as value





{
   'url' : '/api/blog/post/node/{store_type}/{store_id}/{id}',
   'commentsUrl' : '/api/node/{store_type}/{store_id}/{id}/comments',
   'nodeRef' : '<nodeRef>',
   'name' : '<name>',
   'title' : '<title>',
   'content' : '<content>',
   'author' : '<username>',
   'createdOn' : '<date>',
   'modifiedOn' : '<date>',
   'permissions' : [ 'edit' : true, 'publishExt' : true, 'delete' : true ],
   'commentCount' : 10,
   'tags' : [ 'ECM', 'Alfresco'],
  
   /* draft or internally published */
   'isDraft' : true/false,
   'releasedOn' : '<date>',     // only available if isDraft==false
  
   /* Updated flag - always false for draft posts */
   'isUpdated' : true/false,
   'updatedOn' : '<date>',      // only available if isUpdated==true
  
   /* External publishing information */
   'isPublished' : true/false,
   'publishedOn' : '<date>',    // only available if isPublished==true
   'updatedOn' : '<date>',      // only available if isPublished==true
   'postId' : '<id of the external post>',
   'postLink' : '<link to the post>',
   'outOfDate' : true/false,    // whether the external post is older than then internal post
}

Notes:
* releasedOn is only available if isDraft==false
* updatedOn is only available if isUpdated==true
* updatedOn is always false for draft posts
* publishedOn and updatedOn are only available if isPublished==true





{
   'beginOfMonth' : '<date>',      // date marking the begin of the month
   'endOfMonth' : '<date>',        // date marking the end of the month
   'year' : 2008,
   'month' : 6,                    // month index. Attention: January => 0
   'postCount' : 0                 // number of posts
   'firstPostInMonth' : '<date>'   // date of the first post
}

Methods


Get information about the external blog configuration



GET /api/blog/node/{store_type}/{store_id}/{id}
  



Update external blog configuration data:



PUT /api/blog/node/{store_type}/{store_id}/{id}
   => ExternalBlogConfiguration
  



Get a list of posts for a blog



Get all posts (optionally filtered by tag and date range):

GET /api/blog/node/{store_type}/{store_id}/{id}/posts?tag={tag}&fromDate={fromDate}&toDate={toDate}
  



Get the number of posts per month:



GET /api/blog/node/{store_type}/{store_id}/{id}/postspermonth
  



Add a blog post:



POST /api/blog/node/{store_type}/{store_id}/{id}/posts
   => BlogPost
  



Get, update and delete a blog post:



GET /api/blog/post/node/{store_type}/{store_id}/{id}
  

Comment Service


This API allows adding comments to any node in Alfresco.

The fm:forum model is currently used to store comments. The fm:discussable aspect is added to the node and then a topic called 'Comments' added to it. All comments get stored as fm:post nodes into that topic.

The advantage is that comments will also be accessible from the standard webclient.


Data objects


=> Comment



{
   'title' : 'title',
   'content' : 'content'
}


{
   'url' : '/api/comment/node/workspace/SiteStore/fba4e60a-730b-487e-a5a1-e91d16fcc9da',
   'nodeRef' : '<nodeRef>',
   'name' : '<name of file representing comment>',
   'title' : 'title',
   'content' : 'Comment content, html',
   'author' : 'username',
   'createdOn' : '<date>',
   'modifiedOn' : '<date>',
   'isUpdated' : true/false,
   'permissions' : [
      'edit': 'true',
      'delete' : 'true'
   ]
}




Methods


Fetching of comments for a node



GET /api/node/{store_type}/{store_id}/{id}/comments
  

Adding a comment to a node



POST /api/node/{store_type}/{store_id}/{id}/comments
   => Comment
  

Getting, updating and deleting a comment:



GET /api/comment/node/{store_type}/{store_id}/{id}
  

Attachments

    Outcomes