Overview

A workspace is a storage service intended for working copy contents. It allows you to persist working copies of content that are not yet ready to be made commonly available in the main repository. A common use case is autosaving, or previewing articles and their associated resources (such as images) on pages.

A workspace can be seen as a layer on top of the main repository. New content and new content versions written to the workspace only exist on that workspace, invisible to the main repository and other workspaces. Such content are referred to as content drafts.

The workspace service offers read-through semantics. This means that when a content is retrieved from the workspace, the workspace's version of the content is returned, if such exists; otherwise the content is retrieved from the main repository.

Workspaces are identified by a string ID, and many separate workspaces can exist simultaneously.

Creating a workspace

Workspaces exist implicitly; they are created merely by interacting with them. It is possible to read from and write to any workspace without having previously registered it.

Versioning and conflicts

A workspace will only keep one version of a particular content. Any update to that content draft will replace the existing version. There is no conflict detection when updating or deleting on the workspace. Promotion is different since it may create a new version in main repository, in which case normal conflict handling applies.

Variants

The workspace service read operation supports variants just like the regular content API.

LifeCycle hooks

LifeCycle hooks are not applied in any workspace operation except for promote, which applies them just like a regular create or update operation.

Workspace API

The workspace operations have essentially the same interface as the corresponding operation outside workspaces. Here we will describe only the differences.

Operations on workspaces

Normally when a content is created or updated, all the operations are applied as part of the create or update. On workspaces, operations are postponed until the content is promoted to the main store. Because the operations have not been executed yet, any pending operations are included when reading from a workspace. When content on a workspace is updated, any pending operations are discarded and replaced with the operations in the update.

Setting an alias using an operation on a workspace has the immediate effect of reserving the alias, which means that the alias can be used on the workspace, and no other content may be assigned that alias while it is reserved. A reserved alias is assigned to the content on promote, or released for use by other content when one of the following happens:

• The content is removed from the workspace
• The alias is explicitly released
• The content is updated on the workspace without including an operation assigning the alias

Create

Content is created on a workspace by posting to the workspace's endpoint.

Endpoint

curl -X POST http://ace-content-service:8081/content/workspace/<workspace>

Read

Reads a content from a workspace. The workspace service offers read-through semantics, which means that when a content is read from the workspace, the workspace's version of the content is returned, if such exists; otherwise the content is read from the main repository.

Unlike a read operation from main repository which allows for either an unversioned or versioned content id, a read from workspace only accepts an unversioned content id. The resulting version will either be the the draft version (if such exist) or the latest version from main repository.

The response also includes any pending operations that were supplied in the create or update.

Endpoint

curl http://ace-content-service:8081/content/workspace/<workspace>/alias/<namespace>/<alias>

Update

The Update operation is used to update an existing content or content draft. At the time of the update the existing content may either reside only in main repository, in which case a new content draft is created reside only in the workspace (i.e. created on the workspace but not promoted), in which case the existing content draft is replaced * reside in main repository AND workspace (draft version created by previous a workspace update), in which case the existing content draft is replaced.

Workspace updates do not allow the If-Match or If-None-Match headers. Instead the update operation accepts optional "origin" parameter in the JSON input data, which takes an ETag to use when promoting.

Update mode

Updates on workspaces supports the update mode parameter, but only replace and update are supported, merge is not. The content on the workspace will reflect the selected update mode, and the update mode will be applied when the content is promoted.

Endpoint

curl -X PUT http://ace-content-service:8081/content/workspace/<workspace>/alias/<namespace>/<alias>

Delete

A content draft in a workspace can be deleted. Deleting on a workspace affects only the workspace, so just like with update there is no conflict handling. A delete can't be promoted.

Endpoint

curl -X DELETE http://ace-content-service:8081/content/workspace/<workspace>/alias/<namespace>/<alias>

Promote

The Promote operation moves a content draft from a workspace to the main repository.

The actual write operation to main repository may either be an update or a create depending on whether the draft initially arose from an update or create.

In case of an update, if the content was updated in main repository after the draft version was created, the promote will conflict. Conflict checking is always done against the origin stored on the workspace, so after resolving the conflict the draft content must be updated before a new promote attempt can succeed.

Endpoint

curl -X POST http://ace-content-service:8081/content/workspace/<workspace>/alias/<namespace>/<alias>/promote

Clear

Clearing a workspace removes all its content drafts.

Endpoint

curl -X DELETE http://ace-content-service:8081/content/workspace/<workspace>

Info

Retrieves information about a workspace. Currently the workspace ID and a listing of all drafts (their unversioned IDs) can be retrieved.

Endpoint

curl http://ace-content-service:8081/content/workspace/<workspace>

Output

A JSON object containing the following attributes:

Attribute	Data type	Description
workspaceId	alias	The ID of the workspace
drafts	MAP::object	A map with content aliases as key and a (currently) empty object as value

Example

$ curl -X GET -L -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" http://ace-content-service:8081/content/workspace/MyWorkspace
{
   "drafts" : {
      "contentid/3583a182-e00f-40b0-8cd7-dea6459ab073" : {},
      "contentid/5c0ca276-3b3c-4360-a653-13af00efce3c" : {}
   },
   "workspaceId" : "MyWorkspace"
}

Permissions and workspaces

Workspaces do not have per-workspace permissions, instead permissions are purely based on what you could do with the content in a non-workspace setting. In the future workspaces may get a more sophisticated permission system.

For new content that exists only on a workspace: You can create a draft if you could create the content in any context You can delete a draft from a workspace if you could have created it * You can read a draft if you could read it in any context

For content already exists: You can create a draft if you could update the content You can delete a draft if you could have created it * You can read a draft if you can read the original content

Any logged in user can delete a whole workspace.