Protectedpdf 5.0 API Documentation

Introduction

Protectedpdf 5.0 provides a web API allowing other software to automate certain tasks. The API is based on the JSON, or JavaScript Object Notation. You can find more information about JSON at http://en.wikipedia.org/wiki/JSON.

Start by familiarizing yourself with the protectedpdf 5.0 API. You can do so by installing Advanced Rest Client in the Chrome Web Store. This tool will allow you to quickly construct a JSON call and test it against the protectedpdf 5.0 JSON service.

Adding a Document using Advanced Rest Client

To quickly test adding a new document, create a sample JSON file on your desktop and name it “json.txt”. Place the following lines in “json.txt”
------8<------

{

"AllowCopy": true,

"PrintType": "NotAllowed",

"FileName": "TestDocumentFromJson.pdf",

"Title": "Test Document From JSON",

"OptionFloatingLoginForm": true,

"AcroJsGosBehaviourType": "PromptAndCloseDocument",

"FormUniqueId" : "0417da8d-1d69-4175-8840-86c6ebc16e8a",

}
------8<------

Open Google Chrome, then click and click to launch Advanced Rest Client application
At the top, enter your web service URL
Eg. https://protectedpdf.yourdomain.com/api/1.0/doc/
Select the POST checkbox
Under Payload, click the Files (0) tab
Click “Add new file field”
Click the first Choose Files to browse to your json.txt and name the file as “settings”
Click the second Choose Files to browse to your unprotected pdf file and name the file as “rawfile”
Click “Send”
The server response is display below.

Login

Challenge

Relative URL / /api/1.0/login/challenge?clientNonce=<guid
Description / Initiate the login challenge
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
clientNonce / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · The challenge/response metadata (JSON), including:
o ServerNonce (GUID)
· If applicable, an error message (JSON)

Response

Relative URL / /api/1.0/login/response?clientNonce=<guidclientHash=<string> &username=<string&accountId=<guid
Description / Complete the login challenge/response
Note that the clientHash is computed as:
Base64Encode( SHA256( text = clientNonce + serverNonce + user’s password, key = user’s password ) )
Note
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
clientNonce / GUID / Yes
clientHash / String / Yes
Username / String / Yes
AccountId / GUID / No
Expected HTTP code / 200 - OK
Possible return values / · The session metadata (JSON), including:
o ServerHash (String)
o ApiSessionToken (GUID)
o ApiSessonExpiry (timestamp)
o AccountId (GUID)
· If applicable, an error message (JSON)

Account Management

Get an existing account’s metadata

Relative URL / /api/1.0/account/get?id=<guid
Description / Get an existing account’s metadata
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
id / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · The account’s metadata (JSON)
· If applicable, an error message (JSON)

Get all existing accounts’ metadata

Relative URL / /api/1.0/account/getall
Description / Get all existing accounts’ metadata
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / None
Expected HTTP code / 200 - OK
Possible return values / · The accounts’ metadata (JSON)
· If applicable, an error message (JSON)

Add a new account

Relative URL / /api/1.0/account/create
Description / Add a new account to the system
HTTP Method / ☐ GET
☒ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
account / JSON / Yes
Expected HTTP code / 201 - Created
Possible return values / · The account’s metadata (JSON)
· If applicable, an error message (JSON)

Edit an existing account

Relative URL / /api/1.0/account/update
Description / Edit an existing account’s metadata
Note that the account parameter (the document metadata) MUST contain the proper .UniqueId value.
HTTP Method / ☐ GET
☐ POST
☒ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
account / JSON / Yes
Expected HTTP code / 200 - OK
Possible return values / · The document metadata (JSON)
· If applicable, an error message (JSON)

Delete an existing account

Relative URL / /api/1.0/account/delete?id=<guid
Description / Delete an existing account from the system
HTTP Method / ☐ GET
☐ POST
☐ PUT
☒ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
id / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · If applicable, an error message (JSON)

Folder Management

Get an existing folder’s metadata

Relative URL / /api/1.0/folder/get?id=<guid
Description / Get an existing folder’s metadata
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
id / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · The folder’s metadata (JSON)
· If applicable, an error message (JSON)

Get all existing folders’ metadata

Relative URL / /api/1.0/folder/getall
Description / Get all existing folders’ metadata
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / None
Expected HTTP code / 200 - OK
Possible return values / · The folders’ metadata (JSON)
· If applicable, an error message (JSON)

Add a new folder

Relative URL / /api/1.0/folder/create
Description / Add a new folder to the system
HTTP Method / ☐ GET
☒ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
folder / JSON / Yes
Expected HTTP code / 201 - Created
Possible return values / · The folder’s metadata (JSON)
· If applicable, an error message (JSON)

Edit an existing folder

Relative URL / /api/1.0/folder/update
Description / Edit an existing folder’s metadata
Note that the folder parameter (the document metadata) MUST contain the proper .UniqueId value.
HTTP Method / ☐ GET
☐ POST
☒ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
folder / JSON / Yes
Expected HTTP code / 200 - OK
Possible return values / · The document metadata (JSON)
· If applicable, an error message (JSON)

Delete an existing folder

Relative URL / /api/1.0/folder/delete?id=<guid
Description / Delete an existing document from the system
HTTP Method / ☐ GET
☐ POST
☐ PUT
☒ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
id / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · If applicable, an error message (JSON)

Document Management

Get an existing document’s metadata

Relative URL / /api/1.0/doc/get?docUniqueId=<guid>
Description / Get an existing document’s metadata
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
docUniqueId / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · The document’s metadata (JSON)
· If applicable, an error message (JSON)

Add a new document

Relative URL / /api/1.0/doc/post
Description / Add a new document to the system (a.k.a. “protect”)
HTTP Method / ☐ GET
☒ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☒ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
settings / JSON / Yes
rawfile / Binary encoded / Yes
Expected HTTP code / 201 - Created
Possible return values / · The document’s metadata (JSON)
· If applicable, an error message (JSON)

Edit an existing document or its metadata

Relative URL / /api/1.0/doc/put
Description / Edit an existing document’s metadata and/or replace a document’s raw file in the system
Note that the rawfile parameter is not required since the caller can choose to modify the protection settings without replacing the content of the document
Note that the setting parameter (the document metadata) MUST contain the proper .UniqueId value.
HTTP Method / ☐ GET
☐ POST
☒ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☒ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
settings / JSON / Yes
rawfile / Binary encoded / No
Expected HTTP code / 200 - OK
Possible return values / · The document’s metadata (JSON)
· If applicable, an error message (JSON)

Download an existing document

Relative URL / /api/1.0/doc/download?docUniqueId=<guid
Description / Download an existing document from the system
HTTP Method / ☒ GET
☐ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
docUniqueId / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · The protected document (Binary encoded)
· If applicable, an error message (JSON)

Delete an existing document

Relative URL / /api/1.0/doc/delete?docUniqueId=<guid
Description / Delete an existing document from the system
HTTP Method / ☐ GET
☐ POST
☐ PUT
☒ DELETE
Header Content-Type / ☐ multipart/form-data
☐ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
docUniqueId / GUID / Yes
Expected HTTP code / 200 - OK
Possible return values / · If applicable, an error message (JSON)

Unprotect a document

Relative URL / /api/1.0/doc/unprotect
Description / Unprotect an existing document in the system
Note that this does not affect the protected document in any way.
HTTP Method / ☐ GET
☒ POST
☐ PUT
☐ DELETE
Header Content-Type / ☐ multipart/form-data
☒ application/x-www-form-urlencoded
Input parameters / Name / Type / Required?
protectedfile / Binary encoded / Yes
Expected HTTP code / 200 - OK
Possible return values / · The protected document (Binary encoded)
· If applicable, an error message (JSON)

Object data format

The data format is subjected to change. Developers should use Add document or Get document to retrieve the meta data for sample JSON. Developers should also refer to the EIP API documents.

The following JSON will create a new document. There are more attributes available than shown below – you can retrieve an example by using the Get document meta data API call and cross reference the attributes with the Doc API document.

{

"AllowCopy": true,

"PrintType": "NotAllowed",

"FileName": "TestDocumentFromJson.pdf",

"Title": "Test Document From JSON",

"OptionFloatingLoginForm": true,

"AcroJsGosBehaviourType": "PromptAndCloseDocument",

"FormUniqueId" : "0417da8d-1d69-4175-8840-86c6ebc16e8a",

}

This is a brief explanation of the attributes in the JSON above. For more, please refer to the Doc API document.

AllowCopy / Specify the document clipboard setting
· Yes - End-user allowed to copy text from the document
· No - End-user not allowed to copy text from the document
PrintType / Specify the document print setting
· HighResolution - End-user can print document at highest quality available
· LowResolutionOnly - End-user can be print document in low quality only
· NotAllowed - End-user cannot print the document
FileName / Document filename
Title / Document title
OptionFloatingLoginForm / You should use “yes” in this implemenation
AcroJsGosBehaviourType / Specify the Adobe Global Object Security Policy (GOSP) document behavior
PromptAndCloseDocument - Document prompts end user to uncheck GOSP checkbox in Acrobat, then force close the document
PromptOnly - Document prompts end user to uncheck GOSP checkbox in Acrobat
NoPromptNoClose - Document does not prompt the end user at all
FormUniqueId / Specify the form used in this document