Jump to: navigation, search

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
EclipseWeb-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.


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
EclipseWeb-Version: 1.0
Slug: My Dev Workspace

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

{
"Id" : "E9",
"Name" : "My Dev Workspace",
"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.


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/E9 HTTP/1.1
EclipseWeb-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.


Changing workspace metadata

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/E9 HTTP/1.1

{
"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/E9 HTTP/1.1

  
Example Response
HTTP/1.1 204 OK


Detailed Explanation
Deleting a non-existent workspace has no effect.


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/E9 HTTP/1.1
EclipseWeb-Version: 1.0
Slug: "My Project"

  
Example Response
HTTP/1.1 201 OK
Location: http://localhost:8080/workspace/E9/project/A7

{
 "Id": "A7",
 "Location": "http://localhost:8080/workspace/E9/project/A7",
 "ContentLocation" : "http://localhost:8080/file/A7",
 "Name": "My Project"
}
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/E9 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/E9/project/A7"
}  
Example Response
HTTP/1.1 200 OK
Location: http://example.com/workspace/E9/project/A7
ETag: "35fd43td3"
Content-Type: application/json

{
 "ContentLocation": "/file/jrandomuser/destinationProject/",
 "Id": "A7",
 "Location": "/workspace/E9/project/A7",
 "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/E9/project/A7 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.