Chapter 2. REST API

Chapter 2. REST API
Prev		Next

Table of Contents

1. Unsecured REST

1.1. domains
1.2. licensekey

2. Secured REST

2.1. Common structures
2.2. documents/{documentId}/{version}
2.3. documents/{documentId}
2.4. documents/{documentId}/{version}/{pageId}
2.5. pages/{pageId}
2.6. push/{documentId}
2.7. documents

This API is used for integration with other subsystems. The other subsystems consume this api as clients.

1. Unsecured REST

Resources defined in this part can be accesed without authorization. Path to all resources starts with /urest/ prefix.

1.1. domains

List all domains existing in DocumentServer.

1.1.1. Reguest

Domains resource is mapped to following URI accepting GET request:

/urest/domains

1.1.2. Response

XML is returned as response

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
  <Domains ports="7780" sslPorts="7781">
    <Domain description="LightComp v.o.s." name="lightcomp.ep1" />
    <Domain description="Demo LightComp v.o.s." name="lightcomp.ept" /> 
  </Domains>

Ports accepting connections from Tahiti are returned as attributes of <Domains> tag.

ports: semicolon separated list of unsecure ports
sslPorts: semicolon separated list of ssl ports

Domain description is returned in attributes of tag <Domain>

description: human readable name of domain
name: system name of domain

1.2. licensekey

Get demo license key

1.2.1. Request

Domains resource is mapped to following URI accepting GET request:

/urest/licensekey

1.2.2. Response

License key is returned as response with mime type set to application/octetstream.

2. Secured REST

Resources defined in this part can be accessed only by authorized users. HTTP BASIC authorization is used as authorization mechanism. Username is composed from user and domain separated by @.

user: user@domain
password: *****

Path to all resources starts with /rest/ prefix.

2.1. Common structures

Description of common structures returned as result of resource query

2.1.1. Document

Description of document

<Document version="2" id="fd8b511d-6a83-4d58-a9f6-52ed73b0a335" documentTypeName="II - Invoice Incoming" documentType="BookKeeping_II">
- <Attributes>
     ....
  </Attributes>
- <Pages>
     ....
  </Pages>
  </Document>

Document can contain <Attributes> and <Pages> and is described by following attributes

id: unique id of document
version: version of document
documentType: type of document
documentTypeName: human readable localized name of document type

2.1.2. Attribute

Description of one document attribute

  <Attribute localizedName="Period" value="11" name="Period" />

Attribute contains following attributes

name: name of attribute
value: value of attribute
localizedName: human readable localized name of attribute

2.1.3. Page

Description of one page

  <Page id="8161ea78-4636-49a9-a77d-465acc887850" mimeType="APPLICATION/PDF" />

<Page> tag contains following attributes

id: id of page
mimeType: mime type of page

2.2. documents/{documentId}/{version}

Get concrete version of document

2.2.1. Request

Resource is mapped to following URI accepting GET request

/rest/documents/${id}/${version}

Request parameters

id: unique identifier of document
version: version of document
user: execute request in context of given user, when not present execute in context of logged user

2.2.2. Response

XML describing document version is returned.

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
- <Document version="2" id="fd8b511d-6a83-4d58-a9f6-52ed73b0a335" documentTypeName="II - Invoice Incoming" documentType="BookKeeping_II">
- <Attributes>
  <Attribute localizedName="Period" value="11" name="Period" /> 
  <Attribute localizedName="Supplier" value="franta" name="Supplier" /> 
  <Attribute localizedName="Number" value="2010112300" name="FileNumber" /> 
  <Attribute localizedName="Year" value="2010" name="BusinessYear" /> 
  </Attributes>
- <Pages>
  <Page id="8161ea78-4636-49a9-a77d-465acc887850" mimeType="APPLICATION/PDF" /> 
  </Pages>
  </Document>

<Document> tag contains following attributes

id: unique id of document
version: version of document
documentType: type of document
documentTypeName: human readable localized name of document type

<Attribute> tag contains following attributes

name: name of attribute
value: value of attribute
localizedName: human readable localized name of attribute

<Page> tag contains following attributes

id: id of page
mimeType: mime type of page

2.3. documents/{documentId}

Get last version of document.

2.4. documents/{documentId}/{version}/{pageId}

Get page of concrete document version

2.4.1. Request

Resource is mapped to following URI accepting GET request

/rest/documents/${id}/${version}/${pageId}

Request parameters

id: id of document
version: version of document
pageId: id of requested page
user: execute request in context of given user, when not present execute in context of logged user

2.4.2. Response

Page data are retrurned as response or HTTP 404 error code when page doesn't exist.

2.5. pages/{pageId}

Get page by id

2.5.1. Request

Resource is mapped to following URI accepting GET request

/rest/pages/${pageId}

Request attributes

pageId: id of requested page
user: execute request in context of given user, when not present execute in context of logged user

2.5.2. Response

Page data are retrurned as response or HTTP 404 error code when page doesn't exist.

2.6. push/{documentId}

Push last document version to Tahiti

2.6.1. Request

Resource is mapped to following URI accepting GET request

/rest/push/${id}?user=${user}

Request parameters

id: id of document to be pushed to Tahiti
user: connected user to push document to

2.6.2. Response

XML describing status of push operation is returned

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<SearchResult result="OK" version="2" documentId="fd8b511d-6a83-4d58-a9f6-52ed73b0a335" />

<SearchResult> contains result of push operation.

result: OK - successfully push to given user, NOT_CONNECTED when user isn't connected to server
documentId: id of document
version: version of document pushed to user

Return HTTP 404 when document with given id doesn't exist

2.7. documents

Search document by fulltext query

/rest/documents?query=11&start=0

Request attributes

query: fulltext serarch query
start: zero based index of first returned result, attribute is optional, default value is 0
documentType: restrict results to given documentType, attribute is optional
activeVersion: true - search only over last versions (default), false - search over all versions, attribute is optional
user: execute search in context of given user, when not present execute in context of logged user

2.7.1. Requets

Resource is mapped to following URI accepting GET request

2.7.2. Response

XML containing search results are returned

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
- <SearchResults numResults="4">
- <Documents>
- <Document version="2" id="fd8b511d-6a83-4d58-a9f6-52ed73b0a335" documentTypeName="II - Invoice Incoming" documentType="BookKeeping_II">
- <Attributes>
  <Attribute localizedName="Period" value="11" name="Period" /> 
  <Attribute localizedName="Supplier" value="franta" name="Supplier" /> 
  <Attribute localizedName="Number" value="2010112300" name="FileNumber" /> 
  <Attribute localizedName="Year" value="2010" name="BusinessYear" /> 
  </Attributes>
  </Document>
- <Document version="2" id="160632b3-42fa-405e-89b5-e417b0600d3a" documentTypeName="II - Invoice Incoming" documentType="BookKeeping_II">
- <Attributes>
  <Attribute localizedName="Period" value="11" name="Period" /> 
  <Attribute localizedName="Supplier" value="franta" name="Supplier" /> 
  <Attribute localizedName="Number" value="2010112301" name="FileNumber" /> 
  <Attribute localizedName="Year" value="2010" name="BusinessYear" /> 
  </Attributes>
  </Document>
- <Document version="2" id="2743efc7-193b-4fa6-8db7-abdc2925fc96" documentTypeName="II - Invoice Incoming" documentType="BookKeeping_II">
- <Attributes>
  <Attribute localizedName="Period" value="11" name="Period" /> 
  <Attribute localizedName="Supplier" value="franta" name="Supplier" /> 
  <Attribute localizedName="Number" value="2010112302" name="FileNumber" /> 
  <Attribute localizedName="Year" value="2010" name="BusinessYear" /> 
  </Attributes>
  </Document>
- <Document version="1" id="3e8361e7-0725-4e0e-97e8-192b474cb9d1" documentTypeName="API - Advance Payment Order Incoming" documentType="BookKeeping_AII">
- <Attributes>
  <Attribute localizedName="Period" value="11" name="Period" /> 
  <Attribute localizedName="Supplier" value="" name="Supplier" /> 
  <Attribute localizedName="Number" value="0050" name="FileNumber" /> 
  <Attribute localizedName="Year" value="2010" name="BusinessYear" /> 
  </Attributes>
  </Document>
  </Documents>
  </SearchResults>

<SearchResult> tag wrap returned results.

numResults: total number of documents satisfying given query

Prev		Next
Chapter 1. Introduction	Home	Chapter 3. JSON-RPC API