Alfresco REST Design Guidelines (Talk)

[resplin]

Obsolete Pages{{Obsolete}}

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

Table of Contents

• 1 how to deprecate REST API methods


• 2 Java script API


• 3 deep collections


• 4 URL Syntax


• 5 Check in / check out pattern for large graphs of objects


• 6 Empty result sets


• 7 How to format description


• 8 to be processed

how to deprecate REST API methods

How do we remove or change obsolete methods?  
One idea may be to follow the java model and mark the API in some way as 'deprecated'. Mrogers 13:20, 29 December 2008 (UTC) lifecycle attribute implemented.   We now have a 'deprecated' state.

Java script API

Do we need to worry about the Java Script API?    There's lots of implementations (such as Activities feed) that are in Java only.   Should we be saying use java only for those cases such as streaming interfaces that can't be handled by Java Script.   Script API design guidelines

deep collections

We are going to use the dictionary service as a guinea pig for the processing of deep collections.

URL Syntax

Parent / child objacts may have

• level 1, summary : summary details of parent + references of children
  
• level 2, normal : full parent + summary of children
  
• level 3, kitchen sink : full parent + full details of all children.
  

Check in / check out pattern for large graphs of objects

The approach for inbound integrations is loosely based on the “check out / check in”
paradigm, where the system requesting a change is first
required to “check out” the object it wishes to modify from the target system,  modify it as needed and finally “check in” the modified object to the target system.
The primary advantages of this model are:

1. the object that is checked out can be as structurally complex as required,  thereby:
   
   1. Covering a wide variety of use cases through a minimal set of operations
      
   2. improving performance by minimizing the number of round trips in order to retrieve an entire object (including sub-objects)
      
2. merging the updated object with Alfresco's version of the object is simplified, since both versions of the object are available at the same time
   
3. transformation is simplified because merging occurs from the originating system’s representation of the object directly to Alfresco's representation of the object
   
4. validation is simplified since it can be performed by the client prior to attempting to check the changes into Alfresco
   
5. the window of opportunity for concurrent modifications is minimized due to Alfresco retrieving the latest copy of the data immediately prior to modifying and saving it
   
6. development is simplified, due to the small, fixed number of operations that are required, and because the resulting system adheres to the command / query separation principle
   

10:19, 6 November 2008 (UTC) idea for discussion

Empty result sets

Suppose we do a search that finds no data.  How do we represent this?    null, empty array or exception?

How to format description

Here is an example of a formatted description from the CMIS API.    It shows how to format the description field.

I'm putting this forward as a good example to copy.  

Any comments?

  <description>




Inputs:



String url: CMIS service url of the repository to test

String user: username/password for authentication (HTTP BASIC Authentication)

String args: Enum url, headers or both - dictates how arguments are passed to services (Default: url)

boolean validate: true => validate repository responses against CMIS XSDs

boolean trace: true => trace request and response bodies
String tests: names of tests to execute (use * in test name to represent wildcard) (Default: *)

]]>
</description>

And here is an example for a JSON method.

  <description>
  

  If the optional webApp argument is specified then reverts the modified assets within that web app.
  

  JSON data fileds
  

  
all
 
boolean is this submit all? (optional)
  
assets
 
array, of JSON objects containing a path property (optional). If the 'all' option is true then this parameter is ignored
  
paths
 
array, of String paths (optional).  If the 'all' option is true then this parameter is ignored
  
  
  ]]>

Mrogers 10:41, 5 December 2008 (UTC) Using JavaDoc/JSDoc as a template As a developer I need to know the description, parameters, arguments, return value and exception data.  The above example has 'Inputs'.

to be processed

1. consider design of resources, how they relate and requests they support rather than think about design of URIs (that's secondary)
   
2. document in web script description
   
3. atom
   
4. grouping together lists of commands for one unit of work
   
5. check in / check out pattern in discussion.
   
6. accept header negotiation