Provides access to projectdoc documents via a web API.

Type: REST Resource
Extension: Web API Extension
Since: 1.0
Path: rest/projectdoc/1/document

Provides access to projectdoc documents. The service allows to fetch representations by queries and by document identifiers.

Write to Supplier

Since version 1.2 of the projectdoc Web API Extension properties can also be written to the Document Properties Supplier Macro.

Updating existing properties checks for properties defined in any projectdoc macro. New properties, without a reference to an existing property, are written to the Document Properties Marker Macro per default.

Services

The resource provides the following services to access document or property representations.

For information on how to call these REST services, follow these links (alternatively use the REST API Browser to explore the projectdoc Toolbox API):

Document: Provides access to a projectdoc document.
Documents: Supports queries on projectdoc documents, patching projectdoc documents, and creating new documents.
Property: Provides access to a projectdoc document property.
Section: Provides access to a projectdoc document section.

REST API Browser

To use the REST API provided by the projectdoc Toolbox Online Manual or the Web API Extension use the Swagger UI that is installed with the app. The Swagger UI lets you easily explore and use the API from your web browser.

Note that the API Browser link to navigate to the Swagger UI is shown in the Administration Console. The Swagger UI can be accessed by any licensed user.

REST API Link for the projectdoc Toolbox

Selection of the REST API resources and services provided by the Web API Extension for the projectdoc Toolbox shown in the new Swagger UI

Related Components

Document Services Resource: Provides services for projectdoc documents via a web API.
I18N Resource: Services to access localized information via the I18N services.
List of Services: Lists all services provided by the Web API Extension.
Space Resource: Provides access to projectdoc space properties.
Tips for the Web API Examples: Module page to collect tips for using the Web API REST Examples.

Examples

Here are some typical scenarios using these services.

Query Documents

The API allows to execute queries similar to the Display Table Macro.

Query Request

https://username:secret@example.com/confluence/rest/api/projectdoc/1/document.xml?
  select=Name,Short%20Description&
  from=SPACEKEY&
  where=Doctype=blank

The result is a representation that provides a list of all document IDs. In this example, three documents are returned.

Returned Representation

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<documents
  id-list="753671,753673,753675"
  max-result="3"
  start-index="0"
  size="3">
  <document id="753671">
    <property>
      <name>Name</name>
      <value>Blank 1</value>
    </property>
    <property>
      <name>Short Description</name>
      <value>Short description 1.</value>
    </property>
  </document>
  <document id="753673">
    <property>
      <name>Name</name>
      <value>Blank 2</value>
    </property>
    <property>
      <name>Short Description</name>
      <value>Short description 2.</value>
    </property>
  </document>
  <document id="753675">
    <property>
      <name>Name</name>
      <value>Blank 3</value>
    </property>
    <property>
      <name>Short Description</name>
      <value>Short description 3.</value>
    </property>
  </document>
</documents>

If max-result=1 is added as parameter to the request, only the first hit in the result set is returned. Clients may then forward the id-list and select the documents to return. There are also links in the HTTP header to request the next (rel=next) or previous (rel=prev) hit.

If the ID list is specified in the request, no query is executed. Only the select parameter will be taken into account to select on the returned document properties.

Fetch by ID List

Once a list of document IDs is returned, the client my select documents from that list.

ID List Request

https://username:secret@example.com/confluence/rest/api/projectdoc/1/document.xml?
  select=Name,Short%20Description&
  id-list=753671,753673,753675&
  max-result=1&
  start-index=1

With this request, the document with ID 753673 is returned.