Saperion ECM REST API

The Saperion ECM Service is a RESTful web service implementation that provides access to the Saperion ECM system.
This API describes all REST resources and data types provided by this service.

All resources are available at the application path '/api'.

Authentication

The ECM Service supports both HTTP Basic authentication and Token-based authentication schemes. We recommend using the token based approach for better security.

Basic Authentication

To use basic authentication, send an authorization header with the basic schema with every request along with the following two headers:

• X-ECM-LicenseType: <license-type (1=index, 2=query, 3=admin)> If no license header is present, the service uses an index license.
• X-ECM-Tenant: <tenant> this header is optional, it can also be added to the username (such as 'tenant/username').

Example:

     Authorization: Basic YWRtaW5pc3RyYXRvcjpxYQ==
     X-ECM-LicenseType: ADMIN
     X-ECM-Tenant: system
 

Ldap Authentication

To use LDAP authentication, send an authorization header with the basic/ldap schema. If the requested user is an LDAP synced user, then while using basic schema it will forward the request to ldap authenticator to perform LDAP authentication, otherwise it will verify using basic authentication scheme. Using ldap schema it works the opposite way. Following two headers should be sent with every request along with the authorization header.

• X-ECM-LicenseType: <license-type (1=index, 2=query, 3=admin)> If no license header is present, the service uses an index license.
• X-ECM-Tenant: <tenant> this header is optional, it can also be added to the username (such as 'tenant/username').

Example:

     Authorization: Basic YWRtaW5pc3RyYXRvcjpxYQ==
     X-ECM-LicenseType: ADMIN
     X-ECM-Tenant: system
 

     Authorization: Ldap YWRtaW5pc3RyYXRvcjpxYQ==
     X-ECM-LicenseType: ADMIN
     X-ECM-Tenant: system
 

Bearer Authentication

A token can be obtained from the authentication service. To get a token from the authentication service a request must be made to its /api/token endpoint with basic authentication scheme as described above.
To authenticate using the returned token, the token must be sent with an authorization header with the bearer schema.

Example:

 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlY21zVXNlciI6IkFkbWluaXN0cmF0b3IiLCJpc3MiOiJodHRwczovL2VjbXMvIiwiZWNtc0xpY2Vuc2UiOiJJTkRFWCIsImVjbXNUZW5hbnQiOiJTeXN0ZW0iLCJleHAiOjE1NzQyNDQ1NTgsImlhdCI6MTU3NDIzODU1OCwiZWNtc1VzZXJJZGVudGlmaWNhdGlvbiI6ImZ1bGxOYW1lIn0.6niQrumauc8GL_p9JmTpMTPXaQy5Q0ipLAJekxjdlo8
 

Licence Pooling

The ECM Services are completely stateless, which means that there is no such thing like a session that could be used to bind a specific client or user to a license. Therefore, licenses are not bound to users or clients, but to sequences of operations performed by a client. When a client performs an operation by sending a request, the service consumes a license and generates a random license token, which is returned to the client in the response (in a header called X-ECM-LicenseToken). This token can be used by the client in the following request by sending it in the same header. The service then reuses the already consumed license, generates a new random license token and returns it to the client, who will send the new token with the third request and so on.

Each license token can be used exactly once. Each time a license is reused, the service checks if it's type matches the requested license in the request. If not, the service consumes a new license. The ECM Service does not distinguish between the different kinds of user licenses except for the admin licenses. So there are two types of license: User and admin. Admin licenses are required to access the management resources located at /manage/... and for administrative operations in the user management.

Sending multipart requests

There are a few resources which accept multipart/form-data in the request body. The request body for these requests contains a json object which provides the overall structure with pointers to the file data where ever required. The json structure varies with every endpoints and you can find them in the examples provided with the endpoints.

Below is an example multipart request used to archive a document. The body is split into subparts with a boundary string. After each boundary there are some headers which hold metadata regarding that part. After the headers there in a line break and then the content follows. The Content-Type header specifies the mime type of the content that follows. The Content-Disposition header contains a parameter called name which identifies each subpart.

   --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/octet-stream
 Content-Disposition: form-data; name=UUID-ce0eafba-ce0f-4719-a2af-2639c14a3863

 Test multipage Document0
 --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/octet-stream
 Content-Disposition: form-data; name=UUID-6911eac2-2dc5-4e13-9834-d1f995bdbfed

 Test multipage Document1
 --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/octet-stream
 Content-Disposition: form-data; name=UUID-f2472d4f-e225-409d-bc6c-01c15bb1d377

 Test multipage Document2
 --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/octet-stream
 Content-Disposition: form-data; name=UUID-8dabc53b-4de7-471e-b2e3-292fc342275f

 Test multipage Document3
 --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/octet-stream
 Content-Disposition: form-data; name=UUID-28d3697c-3e39-42bc-8046-cdcd33e933cf

 Test multipage Document4
 --79dd896c-5510-47c7-82b7-2c612c7f7847
 Content-Type: application/json; charset=utf-8
 Content-Disposition: form-data; name=structure

 {"archiveReference":{"name":"mytest","contentType":"DOCUMENT"},"index":{"name":{"type":"STRING","propertyValue":"fromPostman"}},"retentionDescription":{"contentType":"test-content-type"},"structure":{"children":[{"content":{"type":"multipart_reference","uri":"cid:UUID-ce0eafba-ce0f-4719-a2af-2639c14a3863"},"fileName":"Test Document","element_type":"file"},{"content":{"type":"multipart_reference","uri":"cid:UUID-6911eac2-2dc5-4e13-9834-d1f995bdbfed"},"fileName":"Test Document","element_type":"file"},{"content":{"type":"multipart_reference","uri":"cid:UUID-f2472d4f-e225-409d-bc6c-01c15bb1d377"},"fileName":"Test Document","element_type":"file"},{"content":{"type":"multipart_reference","uri":"cid:UUID-8dabc53b-4de7-471e-b2e3-292fc342275f"},"fileName":"Test Document","element_type":"file"},{"content":{"type":"multipart_reference","uri":"cid:UUID-28d3697c-3e39-42bc-8046-cdcd33e933cf"},"fileName":"Test Document","element_type":"file"}],"creationDate":"0001-01-01T00:00:00.000+05:30","element_type":"structure"}}
 --79dd896c-5510-47c7-82b7-2c612c7f7847--
 

Searching and paging

All REST endpoints representing a collection of resources support searching or filtering the contents of the collection. A special query language called Saperion Object Query Language (SOQL) is used to define the search criteria. To limit the amount of data transferred from server to client, all resource collections use paging. The SOQL and the paging mechanism are documented here.

Getting started

A getting started guide using the java sdk can be found here.