PublishedDocuments - Huddle/huddle-apis GitHub Wiki

Summary

Documents that have been made public can be aggregated under the company that published them, or the workspace they were published from.

To publish or unpublish a document, please refer to the PublishDocument page.

Get Published Document

This resource supports retrieving previously published document.

User must have access permissions to the workspace to request the published document details.

Example

Request

GET .../publishing/documents/123 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
<DocumentPublicationView>
 <link rel="self" href="..." />
 <link rel="bookmark" href="..." />
 <link rel="alternate" href="..." type="text/html"/>
 <link rel="unpublish" href="..." />
 <actor  rel="publisher" name="Freddy the publisher" email="[email protected]">
  <link rel="self" href="..." />
  <link rel="avatar" href="..." type="image/jpg" />
  <link rel="alternate" href="..." type="text/html" />
 </actor>
 <version title="My amazing document is amazing">
  <link rel="self" href="..." />
  <link rel="workspace" href="..." title="My workspace is the best!" />
  <publishedDate>2014-06-15T09:43:17Z</publishedDate>
  <version>2</version>
  <contentType>application/pdf</contentType>
  <extension>pdf</extension>
 </version>
 <scope>Public</scope>
 <totalViewCount>12405</totalViewCount>
</DocumentPublicationView>

The unpublish link is only present when the caller has permission to unpublish the document.

Link relations

Name Description Methods
self The current URI of this publication. GET
bookmark The public URI to access the published document. GET
alternate The web URI of the document. GET
unpublish The URI to unpublish the document (permission-dependent). DELETE
publisher The user that published the document (actor link). GET

Retrieving a list of published documents by Company

The list of all documents that have been published by an organisation will be advertised by the People resource with a @rel value of publications .

This endpoint gives information on who published which documents, and whether they are published internally or to the web.

Example

Request

GET /publishing/companies/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

<publications>
 <link rel="self" href="..." />
 <link rel="first" href="..." />
 <link rel="last" href="..." />
 <link rel="next" href="..." />
 <link rel="prev" href="..." />
 <totalPublications>50</totalPublications>
 <filteredPublications>2</filteredPublications>
 <publication>
  <link rel="self" href="..." />
  <link rel="bookmark" href="..." />
  <link rel="alternate" href="..." type="text/html"/>
  <link rel="unpublish" href="..." />
  <actor rel="publisher" name="Freddy the publisher" email="[email protected]">
   <link rel="self" href="..." />
   <link rel="avatar" href="..." type="image/jpg" />
   <link rel="alternate" href="..." type="text/html" />
  </actor>
  <version title="My amazing document is amazing">
   <link rel="self" href="..." />
   <link rel="workspace" href="..." title="My workspace is the best!" />
   <publishedDate>2014-06-15T09:43:17Z</publishedDate>
   <version>2</version>
   <contentType>application/pdf</contentType>
   <extension>pdf</extension>
  </version>
  <scope>Public</scope>
  <totalViewCount>12405</totalViewCount>
 </publication>

 <publication>
  <link rel="self" href="..." />
  <link rel="bookmark" href="..." />
  <link rel="alternate" href="..." type="text/html"/>
  <link rel="unpublish" href="..." />
  <actor rel="publisher" name="Jimmy the publisher" email="[email protected]">
   <link rel="self" href="..." />
   <link rel="avatar" href="..." type="image/jpg" />
   <link rel="alternate" href="..." type="text/html" />
  </actor>
  <version title="My everyday document is dull">
   <link rel="self" href="..." />
   <link rel="workspace" href="..." title="My workspace is bland" />
   <publishedDate>2014-06-15T09:43:17Z</publishedDate>
   <version>1</version>
   <contentType>image/jpg</contentType>
   <extension>jpg</extension>
  </version>
  <scope>Public</scope>
  <totalViewCount>12405</totalViewCount>
 </publication>
</publications>

The unpublish link is only present when the caller has permission to unpublish the document.

Parameters

Name Description Methods Optional Default
page Page that you are requesting GET Yes 1
q A list of space separated words by which you want to filter GET Yes

Request with parameter

GET /publishing/companies/123?page=1&q=a_word HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Link relations

Name Description Methods
self The current URI of this publication list. GET
bookmark The public URI to access the published document. GET
alternate The web URI of the document. GET
unpublish The URI to unpublish the document (permission-dependent). DELETE
publisher The user that published the document (actor link). GET
next The URI of the next page of published documents, using sort order specified. GET
prev The URI of the previous page of published documents, using sort order specified. GET
first The URI of the first page of published documents, using sort order specified. GET
last The URI of the last page of published documents, using sort order specified. GET

The 'prev' link is not present on the first page of published documents.

The 'next' link is not present on the last page of published documents.

The 'last' and 'first' links are not present if there is only a single page.

Retrieving a list of published documents by Workspace

The list of all documents that have been published from a workspace will be advertised by the Root folder resource with a @rel value of publications .

This endpoint gives information on who published which documents, and whether they are published internally or to the web.

Example

Request

GET /publishing/workspaces/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

<publications>
 <link rel="self" href="..." />
 <link rel="first" href="..." />
 <link rel="last" href="..." />
 <link rel="next" href="..." />
 <link rel="prev" href="..." />
 <totalPublications>50</totalPublications>
 <filteredPublications>2</filteredPublications>
 <publication>
  <link rel="self" href="..." />
  <link rel="bookmark" href="..." />
  <link rel="alternate" href="..." type="text/html"/>
  <link rel="unpublish" href="..." />
  <actor rel="publisher" name="Freddy the publisher" email="[email protected]">
   <link rel="self" href="..." />
   <link rel="avatar" href="..." type="image/jpg" />
   <link rel="alternate" href="..." type="text/html" />
  </actor>
  <version title="My amazing document is amazing">
   <link rel="self" href="..." />
   <link rel="workspace" href="..." title="My workspace is the best!" />
   <publishedDate>2014-06-15T09:43:17Z</publishedDate>
   <version>2</version>
   <contentType>application/pdf</contentType>
   <extension>pdf</extension>
  </version>
  <scope>Public</scope>
  <totalViewCount>12405</totalViewCount>
 </publication>

 <publication>
  <link rel="self" href="..." />
  <link rel="bookmark" href="..." />
  <link rel="alternate" href="..." type="text/html"/>
  <link rel="unpublish" href="..." />
  <actor rel="publisher" name="Jimmy the publisher" email="[email protected]">
   <link rel="self" href="..." />
   <link rel="avatar" href="..." type="image/jpg" />
   <link rel="alternate" href="..." type="text/html" />
  </actor>
  <version title="My everyday document is dull">
   <link rel="self" href="..." />
   <link rel="workspace" href="..." title="My workspace is bland" />
   <publishedDate>2014-06-15T09:43:17Z</publishedDate>
   <version>1</version>
   <contentType>image/jpg</contentType>
   <extension>jpg</extension>
  </version>
  <scope>Public</scope>
  <totalViewCount>12405</totalViewCount>
 </publication>
</publications>

The unpublish link is only present when the caller has permission to unpublish the document.

Parameters

Name Description Methods Optional Default
page Page that you are requesting GET Yes 1
q A list of space separated words for which you want to filter GET Yes

Request with parameter

GET /publishing/workspaces/123?page=1&q=a_word HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Link relations

Name Description Methods
self The current URI of this publication list. GET
bookmark The public URI to access the published document. GET
alternate The web URI of the document. GET
unpublish The URI to unpublish the document (permission-dependent). DELETE
publisher The user that published the document (actor link). GET
next The URI of the next page of published documents, using sort order specified. GET
prev The URI of the previous page of published documents, using sort order specified. GET
first The URI of the first page of published documents, using sort order specified. GET
last The URI of the last page of published documents, using sort order specified. GET

The 'prev' link is not present on the first page of published documents.

The 'next' link is not present on the last page of published documents.

The 'last' and 'first' links are not present if there is only a single page.

Register a hit on a Published Document

Register a hit on the published content so that the publisher can track / monitor the usage

Parameters

Name Description
documentId the document's Id in Files-BC
versionId the document's versionId
Uri Format ../publishing/tracking/{documentId}/{versionId}

Example

Request

POST ../publishing/tracking/1/2 HTTP/1.1

Response

HTTP/1.1 200 Ok

Use server Caching

Allows the use of server caching when requesting the same content multiple times. The first time a client requests a document, or a list of documents, the server will return the “Last-Modified” date value in the response header.

On any subsequent requests made by the client, where the content has not changed, if the client reuses the “Last-Modified” date header, then, the date will be used in the “If-Modified-Since” HTTP header and the server will respond with a 304, “NotModified” HTTP status code.

Example: First time request

Request

GET /publishing/documents/123 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
Last-Modified: Tue, 09 Dec 2014 15:43:12 GMT
<DocumentPublicationView>
...
</DocumentPublicationView>

Example: Second time request same content

Request

GET /publishing/documents/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
If-Modified-Since: Tue, 09 Dec 2014 15:44:00 GMT

Response

HTTP/1.1 304 Not Modified
Content-Type: application/vnd.huddle.data+xml
⚠️ **GitHub.com Fallback** ⚠️