Lock - Huddle/huddle-apis GitHub Wiki

Summary

Locks are resources attached to a document so that users can control the actions taken on it. A locked document can only be edited by the participants of the lock.

Status

Operation
Locking a document
Releasing a lock
Retrieving a lock
Retrieving locks by owner

Operations

Locking a document (When no Lock exists on the document)

When retrieving a document, the response will advertise a link with a @rel value of lock, which you can use to lock the document. When locking a document, the caller may optionally include a 'lockType' in the request body. This field enables the user to specify what type of lock they want to acquire on the document when locking a document. The options are Exclusive , CoAuthoring or eSign. We default to Exclusive if no request body is present.

Lock Type

Lock type Description
Exclusive Only the lock owner able to edit the document
coAuthoring Allow member to join the edit session via Microsoft Online
eSign ✏️ Start eSign process

Request

POST /files/documents/123/lock HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 peter.gibson-asdasdasdasdasdasdasd
JSON
{
	"lockType": "CoAuthoring"
}
XML
<lockRequest>
	<lockType>CoAuthoring</lockType>
</lockRequest>

Response

If successful, this operation returns a 201 Created with a representation of the lock.

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml
XML
<lock xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/documents/123/lock" />
  <link rel="delete" href="..." />
  <link rel="parent" href="..." />

  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="Peter Gibson" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <lockType>CoAuthoring</lockType>
  <lockDate>2007-10-10T09:02:17Z</lockDate>
</lock>
JSON
{
  "actors" : [{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "owner",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  },{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }],
  "lockType" : "CoAuthoring",
  "lockDate" : "2007-10-10T09:02:17Z",
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

Locking a document (When a lock exist on the document)

If a CoAuthoring lock already exists on a document, a user can join the lock by requesting a CoAuthoring lock.

Lock Type

Lock type Description
Exclusive Only the lock owner able to edit the document
coAuthoring Allow member to join the edit session via Microsoft Online
eSign ✏️ Start eSign process

Request

POST /files/documents/123/lock HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: OAuth2 john.smith-asdasdasdasdasdasdasd
JSON
{
	"lockType": "CoAuthoring"
}
XML
<lockRequest>
	<lockType>CoAuthoring</lockType>
</lockRequest>

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
XML
<lock xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/documents/123/lock" />
  <link rel="delete" href="..." />
  <link rel="parent" href="..." />

  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="Peter Gibson" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
	</actor>
  <actor name="John Smith" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <lockType>CoAuthoring</lockType>
  <lockDate>2007-10-10T09:02:17Z</lockDate>
</lock>
JSON
{
  "actors" : [{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "owner",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  },{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }, {
    "name" : "John Smith",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }],
  "lockType" : "CoAuthoring",
  "lockDate" : "2007-10-10T09:02:17Z",
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

If the existing lock is Exclusive and the user request a CoAuthoring lock we respond with a 409. Similarly if the existing lock is CoAuthoring and the user request a Exclusive lock we respond with a 409.

Error Responses

Case Response Code
If the User is not Authorized 401
If the User is not allowed to take the lock on that document 403
Any data is malformed 400
If the lockType is incompatible 409

Release a lock

When a document is locked, the response will contain a representation of the lock in the body of the response. The lock element will contain a link with a @rel value of delete, which can be used to remove the user's lock on the document. The link for unlocking a document is also advertised within the lock element of a locked document response. If the document has an exclusive lock this would remove the lock on that document. If the document has a CoAuthoring lock then that user would removed from the participants of that lock. However if the document has a CoAuthoring lock and the user is the last participant of the lock, that lock is removed.

Example

In the following example we will unlock document 123 which has a Exclusive lock.

Request

DELETE /files/documents/123/lock
Authorization: OAuth2 peter.gibson-asdasdasdasdasdasdasd

Response

HTTP/1.1 204 No Content
Content-Type: application/vnd.huddle.data+xml

(Note this used to be 200)

In the following example we will unlock document 123 which has a CoAuthoring lock.

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
XML
<lock xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/documents/123/lock" />
  <link rel="delete" href="..." />
  <link rel="parent" href="..." />

  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="John Smith" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <lockType>CoAuthoring</lockType>
  <lockDate>2007-10-10T09:02:17Z</lockDate>
</lock>
JSON
{
  "actors" : [{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "owner",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }, {
    "name" : "John Smith",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }],
  "lockType" : "CoAuthoring",
  "lockDate" : "2007-10-10T09:02:17Z",
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

Error Responses

Case Response Code
If the User is not Authorized 401
If the User is not a participant of the lock 404
If the Lock has been released 410

Retrieving a lock

When a document is locked, the response will contain a representation of the lock in the body of the response. The lock element will contain a link with a @rel value of self, which can be used to retrieve the lock. The link for retrieving a lock is also advertised within the lock element of a locked document response.

Example

In this example, we will get the lock for document 123.

Request

GET /files/documents/123/lock HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
XML
<lock xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="/documents/123/lock" />
  <link rel="delete" href="..." />
  <link rel="parent" href="..." />

  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="Peter Gibson" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="John Smith" email="[email protected]" rel="participant">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <lockType>CoAuthoring</lockType>
  <lockDate>2007-10-10T09:02:17Z</lockDate>
</lock>
JSON
{
  "actors" : [{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "owner",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  },{
    "name" : "Peter Gibson",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }, {
    "name" : "John Smith",
    "email" : "[email protected]",
    "rel" : "participant",
    "links" : [{
      "rel" : "self",
      "href": "..."
    },{
      "rel" : "avatar",
      "href": "..."
    },{
      "rel" : "alternate",
      "href": "..."
    }]
  }],
  "lockType" : "CoAuthoring",
  "lockDate" : "2007-10-10T09:02:17Z",
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

Retrieving locks by owner

It is possible for a user to request a list of locks that they own. This is useful for answering the question: "What documents do I currently have locked?".

Example

In this example, we request locks owned by user 789.

Request

GET /files/lockowners/789/locks HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<locks>
   <link rel="self" href="/files/lockowners/789/locks" />
   <lock>
     <link rel="self" href="/files/documents/123/lock" />
     <link rel="delete" href="/files/documents/123/lock" />
     <createdDate>2013-11-23T09:02:17Z</createdDate>
     <document title="My Cat" content-type="image/jpg">
       <link rel="self" href="/files/documents/123" />
       <link rel="alternate" type="text/html" href="http://my.huddle.net/workspaces/555/files/123" />
       <workspace title="Don't Edit My Cats">
         <link rel="self" href="/workspaces/555" />
         <link rel="alternate" type="text/html" href="http://my.huddle.net/workspaces/555" />
       </workspace>
     </document>
     <actor name="Peter Gibson" email="[email protected]" rel="owner">
       <link rel="self" href="..." />
       <link rel="avatar" href="..." type="image/jpg" />
       <link rel="alternate" href="..." type="text/html" />
     </actor>
     <actor name="Peter Gibson" email="[email protected]" rel="participant">
       <link rel="self" href="..." />
       <link rel="avatar" href="..." type="image/jpg" />
       <link rel="alternate" href="..." type="text/html" />
     </actor>
     <lockType>CoAuthoring</lockType>
     <lockDate>2007-10-10T09:02:17Z</lockDate>
   </lock>
   <lock>
     <link rel="self" href="/files/documents/322/lock" />
     <link rel="delete" href="/files/documents/322/lock" />
     <createdDate>2013-12-01T09:02:17Z</createdDate>
     <document title="My Other Cat" content-type="image/jpg">
         <link rel="self" href="/files/documents/322" />
         <link rel="alternate" type="text/html" href="http://my.huddle.net/workspaces/444/files/322" />
         <workspace title="More Cat Pictures">
	    <link rel="self" href="/workspaces/444" />
            <link rel="alternate" type="text/html" href="http://my.huddle.net/workspaces/444" />
         </workspace>
     </document>
     <actor name="Peter Gibson" email="[email protected]" rel="owner">
       <link rel="self" href="..." />
       <link rel="avatar" href="..." type="image/jpg" />
       <link rel="alternate" href="..." type="text/html" />
     </actor>
     <lockType>Exclusive</lockType>
     <lockDate>2007-10-10T09:02:17Z</lockDate>
   </lock>
</locks>

Syntax

Link relations

Name Description Methods
self The URI of this lock. GET
delete The URI to delete the lock. DELETE
parent The URI of the locked document. GET

Schema

namespace h = "http://schema.huddle.net/2011/02/"
include "base.rnc"

start = lock

lock = element h:lock {
  link+,
  actor
}
⚠️ **GitHub.com Fallback** ⚠️