Orion/Server API/Workspace API

The workspace API provides methods for creating and manipulating workspaces and projects over HTTP. Roughly speaking, workspaces and projects are logical structures for managing and organizing trees of files. This API deals only in that logical metadata, leaving browsing and manipulation of concrete files to the File API.

Actions on workspaces

Getting the list of available workspaces

Overview

The list of available workspaces can be obtained by performing a GET on the root location of the workspace API.

HTTP Method

GET

Example Request

GET /workspace HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"

{
"UserName" : "Sam",
"Id" : "987fd076g5sd6",
"Workspaces" : [
 {
   "Id" : "E9", 
   "Location" : "http://example.com/workspace/E9",
   "LastModified" : 1291907325193",
   "Name" : "My Dev Workspace"
 }
]
}

Detailed Explanation

Workspace metadata is tied to the user owning the workspace. The top level attributes in the response describe the user that performed the request. The Workspaces element lists all workspaces accessible by that user.

Status code details

200 

Everything is ok, all workspaces were found and returned

400 

A malformed request was sent

403 

The user is not authorized

500 

An unknown error occurred while processing the request

Creating a workspace

Overview

A new workspace is created by performing a POST against the root location of the workspace API.

HTTP Method

POST

Example Request

POST /workspace HTTP/1.1
Orion-Version: 1.0
Slug: DevWorkspace

{
"Name" : "DevWorkspace",
}  

Example Response

HTTP/1.1 201 Created
Location: http://example.com/workspace/E9
ETag: "35fd43td3"
Content-Type: application/json

{
"Id" : "E9",
"Name" : "DevWorkspace",
"Location" : "http://example.com/workspace/E9",
"Projects" : [],
"Children" : []
}

Detailed Explanation

Workspaces are uniquely identified by a workspace id ("E9" in the above example). Workspace ids are guaranteed to be unique within a given server, but may overlap ids of workspaces on other servers (they are not UUIDs). Workspaces also have a human-readable "Name" attribute that is not necessarily unique even within a given server. Multiple users on the same server can have different workspaces with the same name.

Status code details

201 

Everything is ok, the requested workspace was created

400 

A malformed request was sent

403 

The user is not authorized

500 

An unknown error occurred while processing the request

Getting workspace metadata

Overview

Metadata information about a workspace is obtained by performing a GET on the workspace location.

HTTP Method

GET

Example Request

GET /workspace/{:workspace_id} HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"

{
"Id" : "E9",
"Name" : "My Dev Workspace",
"Projects" : [
       {
           "Id" : "h8",
           "Location" : "http://example.com/workspace/E9/project/h8"
       }
   ],
   "Children" : [  
   {
   "Name" : "My Project",
   "Location" : "http://example.com/file/h8",
   "Children-Location" : "http://example.com/file/h8?depth=1",
   "Directory" : true
   }
   ]
}

Detailed Explanation

This response is designed to conform to the File API representation, in addition to providing additional workspace-level metadata. This allows a client to treat the response purely as a directory entry, or to access additional metadata attributes if required.

Status code details

200 

Everything is ok, the requested workspace was found and returned

400 

A malformed request was sent

403 

The user is not authorized

404 

The requested workspace could not be found

500 

An unknown error occurred while processing the request

Changing workspace metadata

*** NOTE: This endpoint's functionality is not implemented ***

Overview

Workspace metadata changed by performing a PUT to the workspace location. For example, the workspace name can be changed as shown in the following example.

HTTP Method

PUT

Example Request

PUT /workspace/{:workspace_id} HTTP/1.1
Orion-Version: 1.0

{
"Name" : "My Dev Workspace",
}  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

The request body need only contain the attributes to be changed. Attributes not specified in the request body are untouched. Changes to attributes that are immutable, such as the workspace Id, are ignored.

Deleting a workspace

Overview

To delete a workspace, send a DELETE request to the workspace location.

HTTP Method

DELETE

Example Request

DELETE /workspace/{:workspace_id} HTTP/1.1

  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

Deleting a non-existent workspace has no effect.

Status code details

204 

Everything is ok, the workspace was successfully deleted

400 

A malformed request was sent

403 

The user is not authorized

404 

The requested workspace could not be found

500 

An unknown error occurred while processing the request

Actions on projects

Add a project to a workspace

Overview

Send a POST request to the workspace location to add a project to that workspace. If the project does not already exist it will be created.

HTTP Method

POST

Example Request

POST /workspace/{:workspace_id} HTTP/1.1
Orion-Version: 1.0
Slug: "newProject"
Content-length: 0

  

Example Response

HTTP/1.1 201 OK
Location: http://localhost:8080/workspace/user-OrionContent/project/newProject

{
 "Id": "newProject",
 "Location": "http://localhost:8080/workspace/user-OrionContent/project/newProject",
 "ContentLocation" : "http://localhost:8080/file/user-OrionContent/newProject",
 "Name": "newProject"
}

Detailed Explanation

Projects can belong to more than one workspace. The request entity body may optionally specify the "ContentLocation" of an existing project. In this case, the existing project is added to the workspace. Each project is represented by two resources: the project location which represents the association of a project with a particular workspace, and the project content location, representing the project contents (a file directory tree).

Moving (renaming) a project

Overview

Moving is similar in form to project creation. The post is performed against the parent workspace where the new project is to be created. The source of the move is specified in the request body. The X-Create-Options header differentiates moving from simple project creation. Renaming a project is equivalent to a move, and performed in the same way.

HTTP Method

POST

Example Request

POST /workspace/{:workspace_id} HTTP/1.1
Orion-Version: 1.0
Content-Length: 144
Content-Type: application/json
Slug: destinationProject
X-Create-Options: move

{
"Location" : "http://example.com/workspace/{:workspace_id}/project/{:project_dir}"
}  

Example Response

HTTP/1.1 200 OK
Location: http://example.com/workspace/user-OrionContent/project/destinationProject
ETag: "35fd43td3"
Content-Type: application/json

{
 "ContentLocation": "/file/jrandomuser/destinationProject/",
 "Id": "destinationProject",
 "Location": "/workspace/user-OrionContent/project/destinationProject",
 "Name": "destinationProject"
}

Detailed Explanation

Renaming a project doesn't create a new resource because the project name is not part of the resource name (URI). Therefore this method returns a 200 (OK) response when successful, rather than 201 (CREATED).

Remove a project from a workspace

Overview

A project is removed from a workspace by sending a DELETE request to the resource representing the association of that project with the workspace (the location specified in the response when a project is added to a workspace).

HTTP Method

DELETE

Example Request

DELETE /workspace/{:workspace_id}/project/{:project_dir} HTTP/1.1

  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

This method does not delete the project contents, but rather removes that project from a particular workspace. The project contents are deleted by sending a DELETE request to the project's content location.

References

For details about the X-Create-Options header, see Orion/Server API/File API#The X-Create-Options header.