The Document Services APIs provide developers with a platform for leveraging these features in their applications. Document Services enable any number of users with the requisite privileges to manipulate files and folders located on https://share.acrobat.com. These APIs use a relatively simple REST-based interface, so using it requires that developers know a few details about the following:

• HTTP requests and responses
• Authentication and sessions
• Managing files and folders
• Using Access Control Lists

Accessing the API

Developers typically start with an application or create one (such as an AIR application). The application provides the user interface end users interact with to access the service. It's the developer's job to connect the application to a networking layer that can create the HTTP headers and XML requests that the Share service can parse. You can write your own code or leverage an existing library for this purpose.

HTTP requests and responses

To write applications that leverage Acrobat.com's Document Services, developers should understand the basics of constructing HTTP requests and parsing the HTTP responses. For an overview of service-specific details, see the following:

• Making HTTP Requests
• Handling HTTP responses

Making HTTP Requests

Document Services API requests may consist of the following components:

• Request methods: Supported methods include GET, POST, PUT, DELETE, and MOVE. For certain requests, alternate syntax is supported as described below.
• Request path basics: The root request URL to which parameters may be appended.
• Request authorization: Authorization parameters including a required signature.
• Requests with XML payloads: A request body in XML format that may be required depending on the nature of the request.

Request methods

Each request begins with an HTTP method. Because some clients do not support every HTTP method, alternate syntax is supported. For example, where DELETE is not supported by the client, you can use POST and set a query parameter method to the needed method. For example, the two DELETE requests below are equivalent.

DELETE https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]
POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]?method=DELETE

Request path basics

The base (root) path for all requests is always in the format of <https://><base URL><trailing slash>. The base path is then appended with three possible paths plus request-specific node or path information. The possible paths include the following:

• auth: Gets an authorization token for use with subsequent requests.
• sessions: Starts and ends sessions.
• dc: Identifies files and folders.

https://api.share.acrobat.com/webservices/api/v1/

For example, a dc/share request with a node ID of xyzDoc would be: POST https://api.share.acrobat.com/webservices/api/v1/dc/xyzDoc/share/. All requests must include the trailing slash.

Request authorization

Using an HTTP request header

Most HTTP requests will include an authorization header which have the following requirements:

• New sessions require the parameters apikey, data, and sig. An authorization header for getting the list of nodes in the root folder for a new session could look like:

Authorization: AdobeAuth
   apikey="1dbcbb7111618358a3a6c7f62b152381",
   data="POST https://api.share.acrobat.com/webservices/api/v1/auth/ 1196363602050",
   sig="1bda167c5c4a96483b50788430351b43"

• Existing sessions require the parameters apikey, data, sig, and sessionid. An authorization header for getting the list of nodes in the root folder while in an existing session could look like:

Authorization: AdobeAuth
   sessionid="3bafbc700acd2ca0d38433230a408c2a",
   apikey="6b8b71755fe80445276d0f7d1d5c3d65",
   data="GET https://api.share.acrobat.com/webservices/api/v1/dc/ 1188518642796",
   sig="308421b3840c7bad180e7ea13b32ffde"

• A correctly computed request signature.

Authorization header parameters

Using authorization parameters in an HTTP request

For clients that do not have access to HTTP headers, the authorization parameters can be passed to the API via an HTTP request method. The parameters apikey, calltime, and sig are required. sessionid is only required for existing sessions. Note that data is not required.

A data string must be constructed locally for use in calculating the signature. This string consists of the following:

• The HTTP method (use the intended method if routing through POST)
• Space
• the URL of the request excluding the query parameters and host
• Space
• The query parameter name/value pairs in alphabetical order and separated by spaces (ignore the method parameter if used): apikey, calltime, and sig

For example, the data string for the URL https://api.share.acrobat.com/webservices/api/v1/dc/ could look like:

GET /webservices/api/v1/dc/
   apikey=6b8b71755fe80445276d0f7d1d5c3d65
   calltime=1188518642796
   sessionid=3bafbc700acd2ca0d38433230a408c2a

As with the HTTP authorization header, the signature is formed by taking the MD5 digest of the concatenated data string and the shared secret. After the signature is calculated, the final URL with all the query parameters could appear as below:

https://api.share.acrobat.com/webservices/api/v1/dc/
   ?apikey=6b8b71755fe80445276d0f7d1d5c3d65
   &calltime=1188518642796
   &sessionid=3bafbc700acd2ca0d38433230a408c2a
   &sig=308421b3840c7bad180e7ea13b32ffde

Requests with XML payloads

As you will learn from the subsequent sections that describe in detail how to communicate with the Share API, not all requests include an XML body. However, when they do, the request XML body element is request. Additional elements containing parameters may reside within the request element. While GET requests will not have elements, PUT and POST usually do. As you refer to the following sections, if a feature is associated with a parameter table, then an XML body must be used. If the parameter is not explicitly listed as optional in the tables below, it is required.

<request>
   <some element/>
   <anotherelement>Some parameter value</anotherelement>
</request>

Handling HTTP responses

HTTP responses should be parsed and handled according to the requirements of your application. In general:

• Successful responses will return two items: an HTTP status code of 200 and an optional XML payload in the response body.
• Unsuccessful responses will return with an error code in the 400 or 500 range and will include the error message in the response body.

XML elements common to file and folder nodes

HTTP responses may or may not be returned with an XML payload depending on the nature of the response. Responses that return information about a file or folder node will generally have the elements shown below.

HTTP response attributes: for files and folders

XML elements specific to file nodes

HTTP responses may or may not be returned with an XML payload depending on the nature of the response. Responses that return information about a file nodes will generally have the elements shown below.

HTTP response attributes: for files only

Error Messages for responses

The error messages shown below pertain to all calls and may be returned by any request. Additional errors may be returned for any request-specific errors.

HTTP response: error messages

Authentication and sessions

Before an application can leverage the Share API, the application must initiate an API session on behalf of the user. Doing so requires two steps:

• Requesting an authorization token
• Starting a new session

Requesting an authorization token

Authenticating a request requires that it includes a user's Adobe ID credentials. When the Share service receives the user's username and password, it returns an authorization token.

auth/ gets an authorization token for use with subsequent requests. It is only used for initial authentication. Before starting a session, you must post a user's credentials to receive an authorization token for use with subsequent requests.

Example: auth token request path

POST https://api.share.acrobat.com/webservices/api/v1/auth/

Auth request XML parameters

Example: auth request

<request>
   <username>user@domain.com</username>
   <password>qwerty123</password>
</request>

Authorization response

Response: auth XML parameters

Example: auth response

<response status="ok">
  <authtoken>22e7909e7453cf0b62f656ecae66efdf</authtoken>
</response>

Error messages for authorization

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: auth API request

Starting a new session

After an authentication token has been returned from the previous request, that token can be used once to start a new session.

sessions/ starts and ends Share sessions. After getting an authorization token, use sessions to obtain a Share session ID for use with all subsequent requests. An authorization token can be used only once to request a session. If this session request fails, a new authorization token is required (see Requesting an authorization token).

Example: session token request path

POST https://api.share.acrobat.com/webservices/api/v1/sessions/

Auth request XML parameters

Example: session request

<request>
   <authtoken>22e7909e7453cf0b62f656ecae66efdf</authtoken>
</request>

Authorization response

Session response XML parameters

Example: Response: session XML parameters

<response status="ok">
   <sessionid>1ab1a6190dc1f1f849ca7649190cca83</sessionid>
   <secret>3965c47eb9c937f78d49f3f33e19ca45</secret>
   <level>1</level>
</response>

Authorization error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: session api request

Ending a session

delete immediately ends a session. As shown below, there are alternate methods for ending a session. The session will automatically be deleted after 1 hour of inactivity.

Example: HTTP request: for ending a session (method 1)

DELETE https://api.share.acrobat.com/webservices/api/v1/sessions/[sessionid/]

Example: HTTP request for ending a session (method 2)

POST https://api.share.acrobat.com/webservices/api/v1/sessions/[sessionid/]?method=DELETE

Error messages for ending a session

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: End session request

Managing files and folders

Once the use is authenticated and a session ID obtained through the use of auth and sessions, you application can manipulate files and folders as well as access to them.

dc/ provides requests to work with files and folders. Requests using dc/ may or may not require an XML request payload. In general, GET requests do no require XML while most PUT and POST requests provide XML containing information about files or folders or instructions for the Share API.

For example, using a GET method with dc and a node ID does not require XML. Share simply returns all the child nodes for that node ID. Each child node is returned with the information shown in XML elements common to file and folder nodes as well as XML elements specific to file nodes if it is a file.

Many PUT and POST requests require an XML payload in the request as described below. The XML elements and their parameters listed in the tables below are required.

Listing file and folder information

A dc request with a node ID retrieves information about a given node. The following rules apply:

• If the node ID is omitted, the root folder is used.
• If a folder's node ID is provided, its files and folders are returned in the children element.

Example: dc request: GET for listing node details

GET https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]

Example: dc request: XML payload for listing node details

<response status="ok">
  <node />
  <children>
  <node>
     snip ----------- File and folder details -----------
  <node />
  <node>
     snip ----------- Another node.... until the nth node -----------
  <node /
  </children>
</response>

Uploading a file

To upload a file, construct a POST request with a node ID and an XML payload describing the file. The file will be added to the folder with the given node ID. The following rules apply:

• If a node ID is not specified, the file is uploaded to the root node.
• If the given node ID corresponds to an already existing file, that file will be replaced with the uploaded file.

Example: dc request: POST for file upload

POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid]

Example: dc request: XML payload for file upload

<request>
  <file>
    <name>myfile.pdf</name>
    <description>My File</description>
    <renditions>true</renditions>
  </file>
</request>

dc request XML parameters: file upload

Multi-part POST requests

Files can be uploaded and added through the API using multi-part POST requests. The format for these requests adheres to the standard RFC1867. For details, see http://www.ietf.org/rfc/rfc1867.txt.

Example: dc request: Multi-part POST request

POST /webservices/api/v1/dc/ HTTP/1.1
  Host: api.share.acrobat.com
  Content-type: multipart/form-data; boundary=314159265358979323846
  Content-Length: 12345
  Authorization: AdobeAuth................

  ------------------314159265358979323846

  content-disposition: form-data; name="request"
  <request>
    <file>
      <name>test.pdf</name>
      <description>My File</description>
      <renditions>true</renditions>
    </file>
  </request>

  ------------------314159265358979323846

  content-disposition: form-data; name="file"; filename="test.pdf"
  Content-Type: application/octet-stream
  Content-Transfer-Encoding: binary
  binary data here...

  ------------------314159265358979323846

Upload response

Share returns all the node elements shown in shown in XML elements common to file and folder nodes as well as XML elements specific to file nodes if it is a file.

Example: dc request: File upload response

<response status="ok">
  <node>
  first node data
  </node>

 .....

  <node>
  nth node data
  </node>
</response>

Upload error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: File upload

Adding a folder

To add a folder, construct a POST request with a node ID and an XML payload describing the folder. The folder will be added to the folder with the given node ID. The following rules apply:

• If a node ID is not specified, the folder is uploaded to the root node.
• If the given node ID corresponds to an already existing folder, that folder will be replaced with the uploaded file.

Example: dc request: POST for adding a folder

POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid]

Example: dc request: XML payload for adding a folder

<request>
   <folder>
     <name>New Folder</name>
     <description>This is a new folder</description>
   </folder>
</request>

dc request XML parameters: Adding a folder

Adding a folder response

Share returns all the node elements shown in XML elements common to file and folder nodes as well as XML elements specific to file nodes if it is a file.

Example: Response: for adding a folder

<response status="ok">
  <node>
  first node data
  </node>

 .....

  <node>
  nth node data
  </node>
  </response>

Adding a folder error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: Adding a folder

Deleting a file or folder

To delete a file or folder, construct a request with a node ID as shown below. The node will be deleted to the folder with the given node ID. The following rules apply:

• If a node ID is not specified, the folder is uploaded to the root node.
• If the given node ID corresponds to an already existing folder, that folder will be replaced with the uploaded file.
• The node ID is required because you cannot delete the root folder.

Example: DELETE method for deleting nodes

DELETE https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]

Example: POST method for deleting nodes

POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]?method=DELETE

Deleting a node response

No XML is returned if there are no errors The response header includes the HTTP status code of 200 indicating the request has succeeded.

Deleting a node error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: Deleting a node

Moving or renaming a file or folder

To move or rename a node (a file or a folder), construct a request with a node ID as shown below. The node is moved or renamed as specified in the request. The following rules apply:

• newname is only required for renaming files.
• Moving and renaming can occur in one operation (request).
• Folders are moved in the same way as files. If a folder moves, all of its files and subfolders move with it.

Example: MOVE for renaming nodes

MOVE https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]?[destnodeid=newfolderid&]newname=newid

Example: POST for moving nodes

POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]?method=MOVE

dc request XML parameters: Moving or renaming file and folder

Moving or renaming node response

No XML is returned if there are no errors The response header includes the HTTP status code of 200 indicating the request has succeeded.

Moving or renaming node error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: moving or renaming a node

This is a generic error. Error handling will be further refined in future releases.

Sharing a file

To share a file or a folder, construct a PUT request with a node ID and an XML payload describing the folder. You can specify an optional email message which is automatically sent to those you share the node's URL with. The following rules apply:

• If the level parameter is 1, access is granted to only those users with an Adobe ID that matches one of the given email addresses.
• If the level parameter is 2, anyone can access the file.
• A message is optional.

Example: PUT for sharing files

PUT https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]share/

Example: XML payload for sharing files

<request>
  <share>
    <user>alice@example.com</user>
    <user>bob@example.com</user>
  </share>
  <message>hello world</message>
  <level>2</level>
</request>

dc request XML parameters: File sharing

Sharing a file response

No XML is returned if there are no errors The response header includes the HTTP status code of 200 indicating the request has succeeded.

Sharing a file error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: Sharing a file

This is a generic error. Error handling will be further refined in future releases.

Adding or removing recipients

To add or remove user access to a file that has been shared, construct a POST request with a node ID and an XML payload describing the changes. You can specify an optional email message which is automatically sent to those whose privileges change. The following rules apply:

• Users are specified by valid Adobe ID email addresses.
• Grant access by listing user's email addresses under the parent share element.
• Remove access by listing user's email addresses under the parent unshare element.
• Messages are optional.
• If you want to provide a different message for those with whom you unshare and share documents. In that case, share and unshare in separate requests.

Example: POST for adding or removing recipients

POST https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]share/

Example: XML payload for adding or removing recipients

<request>
  <share>
    <user>alice@example.com</user>
    <user>bob@example.com</user>
  </share>
  <unshare>
    <user>charles@example.com</user>
  </unshare>
  <message>You now have access to my documents (except for Charles).</message>
</request>

dc request XML parameters: Adding or removing recipients

Adding recipient response

No XML is returned if there are no errors The response header includes the HTTP status code of 200 indicating the request has succeeded.

Adding recipient error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: Adding a recipient

This is a generic error. Error handling will be further refined in future releases.

Accessing file renditions

A rendition is the representation of the file provided to the requester. A request can ask for either a thumbnail, the file source, or a PDF. To request a file rendition, construct a request with a node ID. The following rules apply:

• Folder nodes do not have thumbnails or a source.
• thumbnail returns a thumbnail, if any.
• src returns the file source.
• pdf returns the PDF rendition, if any.

Example: GET for a thumbnail

GET https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]thumbnail/

Example: GET for the file source

GET https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]src/

Example: GET for a PDF

GET https://api.share.acrobat.com/webservices/api/v1/dc/[nodeid/]pdf/

dc request XML parameters: Adding or removing recipients

Accessing a file rendition response

Depending on the nature of the request, the service can return the following:

• The actual file thumbnail; and/or,
• The actual file source.

Accessing file rendition error messages

If the request fails, error messages may be returned. See also the general errors described in Error Messages for responses.

Error messages: for accessing a file rendition

Using Access Control Lists

Adobe's Document Services provide a default set of behaviors for controlling document access and permissions. The server knows who the owner is as well as who has the ability to access each node. However, for developers desiring to fine tune this behavior, the Document Services API provides a mechanism for doing so. Permissions can be controlled on a per user ID basis by using access control list (acl) calls which associate user IDs with a role or set of rights.

When an acl call is made, the user IDs and permissions passed to the server replace the original permissions. It is therefore recommended that you update existing permissions rather than provide new permissions without knowing what permissions already exist. Therefore, first GET the permissions and then POST an updated list.

Example: Access control list GET request

GET https://api.share.acrobat.com/webservices/api/v1/[node-id]/acl

The GET request returns a payload as follows:

Example: Access control list GET request payload

<acl>
    <user id="anonymous"              rights="consumer"    />
    <user id="jim@notarealdomain.com" rights="editor"      />
    <user id="jane@dontemailme.org"   rights="contributor" />
    <user id="jack@seriously.net"     rights="full"        />
</acl>

The user ID value of anonymous behaves slightly differently than the other parameters in that it assigns rights to everyone that isn't specifically designated has having a role. That is, if users that do not have the set of rights associated with editor, contributor, or full will have the rights of a consumer if anonymous is used.

After the GET request returns the xml payload with the current permissions, update the list by modifying the payload as needed and returning it in a POST request. An acl POST call expects an xml payload consisting of one or more users and their permissions.

Example: Access control list POST request

POST https://api.share.acrobat.com/webservices/api/v1/[node-id]/acl

Note that if inherit is true, the children of the called node will have the same access control list applied to them. Also, if owner does not retain "full" rights after the update, they may lose the ability to control their own documents.

Example: Access control list POST request payload

<acl inherit="true|false">
    <user id="anonymous"              rights="consumer"    />
    <user id="jim@notarealdomain.com" rights="editor"      />
    <user id="jane@dontemailme.org"   rights="contributor" />
    <user id="jack@seriously.net"     rights="full"        />
</acl>

Permissions for access control list calls