This is my first shot at a rough API for the Kalivo/JCR interface. I've tried hard to be Restful, but doubtless failed in numerous ways. Comments please. Not included here are the search API and the docType API. They'll be forthcoming.

initialization
==============================================
POST /account/<acct #> (secure)
POST /account?delete

put/get
==============================================
POST /item/item_name => head
GET /item/item_id => head
GET /item/item_id/version => version
POST /item/item_id?delete
GET /directory/node_id => returns XML containing files, timestamps, sizes, ACLs, metadata, version data

statistics - do we need this?
==============================================
GET /stats/count
GET /stats/count/node_id => file count by app
GET /stats/usage
GET /stats/usage/node_id => usage by app
GET /stats/cost => not sure this data is available
GET /stats/cost/node_id => cost by app

Search - TBD

==============================================
 

Document Type - TBD
==============================================

Taxonomy - for extensibility only - not in initial releases
==============================================
POST /node/path => generates full path (i.e. a/b/c creates a, a/b and a/b/c)
POST /node/path?delete => removes full path (i.e. a/b/c removes a/b/c, a/b and a)
GET /node/path

security - not in initial releases
==============================================
POST /acl/node_id/<acl>

The first 'release' of the storage service will support the following major features:

• Check-in/check-out - the ability to add files to the storage repository (upload) and get them back (download).
• Versioning - the ability to track changes in items and to 'roll back' to a previous item.
• Repository Browsing - the ability to get a representative view of the items in the repository, to the extent allowed by security restrictions.
  

Major features not supported in the initial release, but planned for upcoming releases:

• Security - the ability to restrict a user's ability to store and retrieve items to and from certain directories
• Taxonomies - the ability to structure the information in the repository in a hierarchical manner
• Search - the ability to search the repository.

The storage service uses the following terminology:

• Repository - the database which contains all of the directories and items managed by the storage service.
• Item - any file or document managed by the storage service.
• Directory - an abstract term for a collection of Items.

The API supports a few useful conventions:

• Authorization failures will cause the service to return HTTP code 401
• Item Not Found failures will cause the service to return HTTP code 404
• Internal Errors will cause the service to return HTTP code 500
• As a general guideline, the service will attempt to return appropriate HTTP codes wherever possible.

• POST /item => Post an item to the repository. In the initial release, all items will be posted to the same directory. Taxonomy support will come in a later release. Posting over an item of the same name will version the existing item (i.e. both items will exist in the repository.)
  • Authorization Failure: 401 (TBD)
  • Internal Error: 500
  • Success:

 <RESULT>
  <FILENAME>aaa.txt</FILENAME>
  <PATH>aaa.txt</PATH>
  <TYPE>text/plain</TYPE>
  <ID>df970957-9a8c-4d5a-a7e8-92c4ea5f6e98</ID>
</RESULT>

The actual format of the ID return is unimportant. What is important to know is that the ID is guaranteed to be globally unique and may be used to retrieve the item later.

• POST /item/<item_name> => Post an item to the repository and name it <item_name>.  The example below shows the results from the seventh upload of a given file.
  
  • Authorization Failure: 401 (TBD)
  • Internal Error: 500
  • Success:

 <RESULT>
  <FILENAME>aaa.txt</FILENAME>
  <PATH>aaa.txt</PATH>
  <TYPE>text/plain</TYPE>
  <ID>df970957-9a8c-4d5a-a7e8-92c4ea5f6e98</ID>
  <HISTORY>

    <VERSION name="jcr:rootVersion">Wed Nov 07 14:59:11 CST 2007</VERSION>
    <VERSION name="1.0">Wed Nov 07 14:59:12 CST 2007</VERSION>
    <VERSION name="1.1">Wed Nov 07 14:59:27 CST 2007</VERSION>
    <VERSION name="1.2">Wed Nov 07 14:59:39 CST 2007</VERSION>
    <VERSION name="1.3">Wed Nov 07 14:59:48 CST 2007</VERSION>
    <VERSION name="1.4">Wed Nov 07 14:59:55 CST 2007</VERSION>
    <VERSION name="1.5">Wed Nov 07 15:00:03 CST 2007</VERSION>
    <VERSION name="1.6">Wed Nov 07 15:00:10 CST 2007</VERSION>
    <VERSION name="1.7">Wed Nov 07 15:00:18 CST 2007</VERSION>
  </HISTORY>
</RESULT> 

• DELETE /item/<item_id>
• POST /item/<item_id>?_method=delete => both forms 'soft delete' the item, removing it from directory listings, but leaving it in the repository. It's unclear at this point in time how permalinks to deleted files will be handled.
  • Failed authorization: 401 (TBD)
  • Nonexistent item_id: 404
  • Internal error: 500
    

• GET /directory?taxonomy => returns the contents of the repository hierarchically, complete with version data. This won't scale and will eventually be paged.
  • Failed authorization: 401 (TBD)
  • Internal Error: 500
  • Success:

<RESPONSE>
  <DIRECTORY name="com">
    <DIRECTORY name="microsoft">
      <DIRECTORY name="download">
        <DIRECTORY name="388e7205-bc10">
           <ITEM id="f9062443-0ed3-4736-bfda-781d2c65e975" mimeType="application/msword" name="csharp language specification.doc"/>
        </DIRECTORY>
      </DIRECTORY>
    </DIRECTORY>
  </DIRECTORY>
</RESPONSE>

• GET /directory?flat => returns the contents of the entire repository as a list of files, complete with version data. This won't scale and will eventually be paged.
  • Failed authorization: 401 (TBD)
  • Internal Error: 500
  • Success:

<RESPONSE>
  <ITEM id="f9062443-0ed3-4736-bfda-781d2c65e975" mimeType="application/msword" name="com/microsoft/download/388e7205-bc10/csharp language specification.doc"/>
  <ITEM id="4fd4b9aa-6dec-46ef-8024-88ae224145ce" mimeType="application/msword" name="com/microsoft/download/68a81446-cd73/wf_xpsp2.doc"/>
</RESPONSE>

• GET /item/<item_id> => returns the requested file
  • Authorization Failure: 401 (TBD)
  • Nonexistent item:id: 404
  • Internal Error: 500

• GET /item/<item_id>/<version> = returns the request version of the requests file
  • Authorization Failure: 401 (TBD)
  • Nonexistent item_id: 404
  • Nonexistent version: 404
  • Internal Error: 500

Storage Service APIs yet to be published, in roughly this order:

• search API
  • GET /item?parm1=val1&parm2=val2&parm3=val3&parm4=val4
• account management/usage API
  • create new 'accounts' - track service accounts to S3 accounts for billing purposes
  • get usage stats - space, bandwidth, cost
• taxonomy API
  • Generate and maintain a folder-like hierarchy, and allow the repository, search, account management and security APIs to access it
• security API
  • Generate and maintain ACLs
• docType API
  • Generate and maintain custom document types (i.e. sets of properties that are supported and searchable)

• Be nice to include definitions for "item", "directory" at the top 
• Please move the common returned codes from underneath each method to a section above the APIs. Only returns that stipulate a payload or vary from expected RA behavior should be individually described
• On the POST /item method, please include a description of the returned GUID in the text
• POST /item/item_name comments:
  • Shouldn't this be a PUT ?
  • How does the service know what ID I'm updating?  aka where is the GUID?
• POST /item/item_id?delete should be DELETE /item/item_guid.  If we want to overload it would be POST /item/item_guid?_method=delete
• If I do a GET /directory why do I get back nothing named "directory" in the XML?

Instructions for the Initial Deployment - Linux Version

The following instructions are for storage service deployment only. Tomcat scripting support for monit and init.d may be borrowed from an existing deployment. These commands must be run as root. 

cd /usr/local/

mkdir storage
chmod 700 storage

Check out the latest application: 

svn co svn://72.249.82.8/service_storage/trunk/deploy

If /usr/local/tomcat doesn't exist, then run the following commands:

tar zxvf deploy/apache-tomcat-5.5.25.tar.gz

mv apache-tomcat-5.5.25 tomcat

mv tomcat/common/endorsed/xml-apis.jar tomcat/common/endorsed/xml-apis.jar.bak

rm -Rf tomcat/webapps/ROOT

Deploy the application:

cp deploy/bsgstorageservice.war tomcat/webapps/ROOT.war

Clean up after ourselves:

rm -Rf deploy

Start Tomcat:

/etc/init.d/tomcat start

monit start tomcat

 

Instructions for Updating the Service

Stop tomcat. I use both monit and the init.d script to stop tomcat because I like the feedback I get from the script, but I need to be sure that monit doesn't restart tomcat halfway through my deployment:

monit stop tomcat

/etc/init.d/tomcat stop

Change directories to the parent of TOMCAT_HOME:

cd /usr/local/

Check out the latest application: 

svn co svn://72.249.82.8/service_storage/trunk/deploy

Remove the existing application from Tomcat:

rm -Rf tomcat/webapps/bsgstorageservice
rm -f tomcat/webapps/bsgstorageservice.war
rm -Rf tomcat/webapps/ROOT

rm -f tomcat/webapps/ROOT.war 

Deploy the new WAR:

cp deploy/bsgstorageservice.war tomcat/webapps/ROOT.war

Restart Tomcat:

/etc/init.d/tomcat start

monit start tomcat 

Clean up after ourselves:

rm -Rf deploy

Instructions for an initial Windows deployment

Make sure you have JRE 1.5.0_12 installed locally. It's likely that any 1.5.0 will do, but I've only tested 6 and 12.

Get the relevent files from SVN:

cd \
mkdir ss
cd ss
rmdir /S deploy
svn co svn://72.249.82.8/service_storage/trunk/deploy

Choose a location for the Tomcat install. I suggest:

set CATALINA_HOME=C:\Program Files\Apache Software Foundation\Tomcat 5.5

Install Tomcat 5.5.25. Select "Full Install" and select JRE1.5.0_12 when it asks you which Java install to use. Otherwise, select the defaults. Do not run Tomcat when it offers you the opportunity at the end of the installation.

deploy\windows\apache-tomcat-5.5.25.exe

Overwrite parts of your Tomcat install with files you got from the repository:

copy /Y deploy\windows\conf\server.xml "%CATALINA_HOME%\conf"

copy /Y deploy\windows\bin\*.bat "%CATALINA_HOME%\bin"

If you plan to develop Storage Service code, you'll also want to do the following:

copy /Y deploy\windows\common\lib\*.jar "%CATALINA_HOME%\common\lib"

Replace the ROOT app with the Storage Service app. This is what I had to do to steal the main URL (storage.bsgplatform.com) from Tomcat

rmdir /S "%CATALINA_HOME%\webapps\ROOT

copy /Y deploy\bsgstorageservice.war "C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\ROOT.war"

Start Tomcat - because you have no repository yet, there will be numerous exceptions in the startup log - ignore them.

"%CATALINA_HOME%\bin\startup.bat"

Edit jackrabbit-s3.properties and set the correct S3 credentials. They are initially blank because we want to do everything we can to prevent test environments accidentally impacting the production repository.

notepad "%CATALINA_HOME%\webapps\ROOT\WEB-INF\jackrabbit-s3.properties 

Stop and restart Tomcat so the change can take effect.

"%CATALINA_HOME%\bin\shutdown.bat"

"%CATALINA_HOME%\bin\startup.bat"

Once Tomcat is running again, test it by trying to hit:

http://localhost:3002

If you see the Storage Service API, then the install was successful.

Create the repository from the following page. Hit the 'create' button under the 'Create a new Repository' section, using the default value for 'Repository Home":
 

http://localhost:3002/administration/

You should receive a response that indicates that the repository is now properly configured and running properly.

Browse your repository here (it should initially be empty, of course):

http://localhost:3002/repository/default/

Search it here:

http://localhost:3002/search.jsp

Populate it here:

http://localhost:3002/populate.jsp

Use these files to start and stop the storage service:

"%CATALINA_HOME%\bin\startup.bat"
"%CATALINA_HOME%\bin\shutdown.bat"

Alternatively, manipulate it through the service panel.

When the installation is complete, you can remove the temp directory from your drive (\ss)

To publish Storage Service updates

Shut down everything that might have a lock on your local repository or the repository directories (\usr\local\storage), Tomcat being the chief culprit.

Get the relevent files from SVN:

cd \
mkdir ss
cd ss
rmdir /S deploy
svn co svn://72.249.82.8/service_storage/trunk/deploy

Choose a location for the Tomcat install. I suggest:

set CATALINA_HOME=C:\Program Files\Apache Software Foundation\Tomcat 5.5

Replace the ROOT app with the Storage Service app. This is what I had to do to steal the main URL (storage.bsgplatform.com) from Tomcat:

rmdir /S "%CATALINA_HOME%\webapps\ROOT"

copy /Y deploy\bsgstorageservice.war "%CATALINA_HOME%\webapps\ROOT.war"

Start Tomcat to explode the WAR:

"%CATALINA_HOME%\bin\startup.bat"

notepad "%CATALINA_HOME%\webapps\ROOT\WEB-INF\jackrabbit-s3.properties

Restart Tomcat to get the changes to take effect: 

"%CATALINA_HOME%\bin\shutdown.bat"

"%CATALINA_HOME%\bin\startup.bat"

To reinitialize your Windows JCR repository:

WARNING - the process outlined below is utterly destructive, and you will lose the entire repository. At this point in time, there are only two repositories - one for TEST and one for PRODUCTION. As long as we are sharing a TEST repository, following the instructions below will clear not only your own test environment, but the global TEST environment. 

Get and install Bucket Explorer. This is my favorite S3 client of the several I've evaluated.

Shut down everything that might have a lock on your local repository or the repository directories (\usr\local\storage), Tomcat being the chief culprit.

Delete your local repository artifacts:

cd \usr\local\storage
rmdir /S jackrabbit

Open Bucket Explorer, log into the repository using these credentials. These are the TEST credentials:

Access Key: 0C18F6Q6KVXQ8WFDV002
Secret Key: kPoGEZJ4YbEdsALCrYL3zelmWdNNjiY98q2Q7YTX

Using Bucket Explorer, delete your artifact folders - they're identifiable as <access key>.<artifact name>. At present, there are only two:

0C18F6Q6KVXQ8WFDV002.repository

0C18F6Q6KVXQ8WFDV002.workspace

Restart Tomcat, ignoring the exceptions in the log caused by the absence of the repository.

    "%CATALINA_HOME%\bin\startup.bat"

Reinitialize and verify your repository as outlined in detail above, starting here:

http://localhost:3002/administration/