Summary

'Pinned' items are a list of either Documents or Folders, curated by Workspace Managers, but visible to all members of the workspace. Folder permissions are respected, so when a call is made for a particular user, only items the user is permitted to see will be returned.

Status

Operation
Retrieving the pins for a workspace
Pinning a document
Unpinning a document
Pinning a folder
Unpinning a document

Retrieving the pins for a workspace

If pinning is enabled for the workspace, a workspace element will contain a link with a @rel value of pinneditems.

To get a list of pinned items for a workspace (either Documents or Folders), make a GET request to this Uri.

Example

Request

GET files/workspaces/27/pinneditems HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "links": [
        {"rel": "self", "href": "files/workspaces/27/pinneditems"},
    ],
    "items": [
        {
            "type": "folder",
            "title": "sub folder",
            "description": "my subfolder",
            "links": [
              {"rel": "self", "href": "..." },
              {"rel": "unpin", "href": "..." },
              {"rel": "alternate", "href": "...", type: "text/html"},
              {"rel": "paged-folder", "href": "..."}
            ]
        },
        {
            "type": "document",
            "title": "document title",
            "description": "document description",
            "mimeType": "application/pdf",
            "extension": "pdf",
            "thumbnails": [
              {
               "links": [
                {"rel": "content", "href": "..."}
               ],
               "type": "medium"
             }
            ],
            "links": [
              {"rel": "self", "href": "..." },
              {"rel": "unpin", "href": "..." },
              {"rel": "alternate", "href": "...", type: "text/html"},
              {"rel": "content", "href": "..."}
            ]
        }
    ]
}

---

Pinning a document

(Workspace Managers only)

If it is possible to pin this document, the document resource will advertise a link with a @rel of pin.

Example

In this example, the user wishes to pin a document which has a self uri of .../files/documents/1.

Request

POST .../files/documents/1/pin HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions, or Too Many Pins
404	Specified document not found
409	Already pinned
410	Specified document is deleted

Response

HTTP/1.1 200 OK

Unpinning a document

(Workspace Managers only) If pinned, the document resource will have a Pin element. A DELETE request to the advertised delete uri will remove the pin.

Alternatively, there items entry in the list of pins for a workspace will contain the a link with a @rel of unpin. This is the same delete uri for the pin and can be used to perform the unpin operation.

Example

In this example, the user wishes to remove a pinned document, which has a delete uri of .../files/documents/1/pin.

Request

DELETE .../files/documents/1/pin HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions
404	Specified document not found, or not pinned
410	Specified document is deleted

---

Pinning a folder

(Workspace Managers only) It is possible to add a folder to the list of 'pinned' items for the workspace.

If it is possible to pin this folder, the folder resource will advertise a link with a @rel of pin.

Example

In this example, the user wishes to pin a folder which has a self uri of .../files/folders/1.

Request

POST .../files/folders/1/pin HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions, or Too Many Pins
404	Specified folder not found
409	Already pinned
410	Specified folder is deleted

Unpinning a folder

(Workspace Managers only) If pinned, and it is possible to unpin this folder, the folder resource will contain a Pin element. A DELETE request to the advertised delete uri will remove the pin.

Alternatively, there items entry in the list of pins for a workspace will contain the a link with a @rel of unpin. This is the same delete uri for the pin and can be used to perform the unpin operation.

Example

In this example, the user wishes to pin a folder which has a delete uri of .../files/folders/1.

Request

DELETE .../files/folders/1/pin HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions
404	Specified folder not found, or not pinned
410	Specified folder is deleted

---