Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

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

Back to the top