Lock - Huddle/huddle-apis GitHub Wiki

Lock

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.

Operations

Method Path Purpose Details
POST /files/documents/123/lock Locking a document Jump
DELETE /files/documents/123/lock Releasing a lock Jump
GET /files/documents/123/lock Retrieving a lock Jump
GET /files/lockowners/789/locks Retrieving locks by owner Jump

Locking a document (when no lock exists)

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. The options are Exclusive, CoAuthoring or eSign. The default is Exclusive if no request body is present.

Lock type

Lock type Description
Exclusive Only the lock owner is able to edit the document.
CoAuthoring Allow members to join the edit session via Microsoft Online.
eSign Start an eSign process. Only supported on PDF documents.

Request

POST /files/documents/123/lock HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer 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>
  <lockId>456</lockId>
</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",
  "lockId" : 456,
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

Locking a document (when a lock already exists)

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 is able to edit the document.
CoAuthoring Allow members to join the edit session via Microsoft Online.
eSign Start an eSign process. Only supported on PDF documents.

Request

POST /files/documents/123/lock HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer 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>
  <lockId>456</lockId>
</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",
  "lockId" : 456,
  "links" : [{
    "rel" : "self",
    "href" : "..."
  }, {
    "rel" : "delete",
    "href" : "..."
  }, {
    "rel" : "parent",
    "href" : "..."
  }]
}

If the existing lock is Exclusive and the user requests a CoAuthoring lock, the server responds with 409 Conflict. Similarly, if the existing lock is CoAuthoring and the user requests an Exclusive lock, the server responds with 409 Conflict.

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 with the existing lock 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.

If the document has an Exclusive lock, this removes the lock entirely. If the document has a CoAuthoring lock, the user is removed from the participants. If the user is the last participant, the lock is removed entirely.

Example: releasing an Exclusive lock

Request

DELETE /files/documents/123/lock HTTP/1.1
Authorization: Bearer peter.gibson-asdasdasdasdasdasdasd

Response

HTTP/1.1 200 OK

Example: releasing a CoAuthoring lock

Request

DELETE /files/documents/123/lock HTTP/1.1
Authorization: Bearer john.smith-asdasdasdasdasdasdasd

Response

The remaining participants are returned in the response body.

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>
  <lockId>456</lockId>
</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",
  "lockId" : 456,
  "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 403
If the Lock has been released 410
If there is an upload in progress or incomplete upload 409

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: Bearer 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>
  <lockId>456</lockId>
</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",
  "lockId" : 456,
  "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 allowed to view the lock 403
If no lock exists on the document 404

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: Bearer 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" />
     <created>2013-11-23T09:02:17Z</created>
     <document title="My Cat" content-type="image/jpg" extension="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" />
     <created>2013-12-01T09:02:17Z</created>
     <document title="My Other Cat" content-type="image/jpg" extension="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 or folder. GET

Schema

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

start = lock

lock = element h:lock {
  link+,
  actor+,
  element h:lockId {xsd:long}?,
  element h:lockType {xsd:string},
  element h:lockDate {xsd:dateTime}?
}
⚠️ **GitHub.com Fallback** ⚠️