API
This document introduces the Web API for eLegere.
The eLegere Web API enables the web clients to request data from eLegere's applications. The returned data depends on the level of authorized access from the user's session: if the user hasn't a specific authorization, the API won't return some data.
Note
The API returns all the responses as either JSON objects or content stream.
Every time your third-party integration requests data through the API, the returned JSON objects encodes the different data types according to specific formats. Check the eLegere Data Types reference to learn about the eLegere data types' format.
Tip
If a method requires the Application Id, check the section Retrieve Application's ID to learn how to retrieve an application's Id.
Other Id types: recover the necessary Id by checking the eLegere's meta-data database.
Note
There are limitations for both the URL requests and the requests' Body in POST:
- URL String for the request has the maximum length of 2048 characters.
- The API accepts Body size for the request up to 60 Mb.
These limitations are independent from eLegere.
Info
Check the Conventions and HTTP Status Codes to learn about terms conventions and HTTP Status Codes responses.
Warning
In the Header description, SessionToken stands for the access_token
in the Request.
Authentication¶
Authentication
The method enables the user to authenticate to the eLegere's environment. The service returns a Session Token with everything required for the access.
Request¶
Method | POST |
URL | {base_url}/identityprovider/connect/token |
Protocols | HTTPS |
ContentType | application/x-www-form-urlencoded |
Headers | no headers required |
Return | JSON Object |
Body:¶
1 |
|
Examples¶
Create a WEB request to authorize a user's access and obtain a Session Token for them. The JSON contains the Session Token, the expiration time in milliseconds, the type, and the scope.
Raw Request:
1 2 3 |
|
Raw Response:
1 2 3 4 5 6 7 8 |
|
Get Items¶
Data
The method queries an application through the WorkspaceId, ApplicationId, and Session Token to obtain an application's data. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/items |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | Array of JSON Objects |
Body:¶
1 |
|
Examples¶
The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrive the data. The body contains the string with the query. The query provides the parameters for the top, exceptions, and the order and field for the sorting.
Raw Request:
1 2 3 4 5 6 7 8 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Get Items Count¶
Data
The method queries an application through the WorkspaceId, ApplicationId, and Session Token to count the exact number of items in the application satisfying the criteria.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/items |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | JSON Object |
Body:¶
1 |
|
Examples¶
The request provides the Session Token for the access, the response file's format, the workspace Id (i.e the Domain) and application's Id for the the API to retrive the info. The response reports the number of items according to the criteria specified in the body.
Raw Request:
1 2 3 4 5 6 7 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 10 11 |
|
Save¶
Data
The method queries an application through the WorkspaceId, ApplicationId, and Session Token to create or update a row on the application's table.
If you want to create a new row, insert a negative progressive number as row's Id.
E.g. If you save three new rows, insert -1
as Id of the first row, -2
for the second, and so on. The service will assign a proper database Id after the save.
If you want to update an item:
1) Call the Get Items API method to retrive the information of the rows to update.
2) Recover the TIMESTAMP
key value from the retrieved objects for the rows to be updated.
3) Call the Save method; insert in TIMESTAMP
keys the values from step (2) in the objects to save the rows.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/items/save |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | Array of JSON Objects |
Body:¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Examples¶
The request contains the row's information as object: each row's field and value corresponds to an object's key. The response provides an object detailing if the saving process was successful (i.e. the key "IsSaveSuccesfully"), what has been saved, created, edited or deleted, and a link to the Master's row (i.e. the key "MasterRowLink" in the object).
Raw Request:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
Delete¶
Data
The method queries an application through the WorkspaceId, ApplicationId, and Session Token to delete a row from the application's table.
Delete a row by inserting its Id in the object's Id
key and its Timestamp in the TIMESTAMP
key.
The method deletes the row with that particular Id and Timestamp.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/items/delete |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | Array of JSON Objects |
Body:¶
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Examples¶
The request contains the row's Id and its Timestamp. These two values are essential to identify the row to be deleted.
After the deletion, the Response object reports if the operation has been successful through the IsSaveSuccesfully
key's value.
Raw Request:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Get Attachments List¶
Data
The method retrieves the attachments list of a row in an application starting from the row's Id and attachments' folder Id.
Note
You can obtain a row's Id through the Get Items method. Replace it in the URL to identify the row's attachments list.
Info
The last part of the URL and FolderId eq FOLDERID
is optional. You need the FOLDERID
only to retrive the attachment list if the attachment is nested in a folder within the row's attachments folders' tree. Check Filters' Query Composition for more info about the operators and options eLegere supports for the items' queries.
Request¶
Method | GET |
URL | {base_url}/SmartExplorerApi/api/attachments?$filter=ParentId eq ROWID and FolderId eq FOLDERID |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | Array of JSON Objects |
Examples¶
The method retrieves the row's attachments list starting from the row's Id. The array object contains an object for each row's attachment. Each object details the individual attachment's information.
Raw Request:
1 2 3 4 5 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Download Attachment¶
Data
The method accesses through a Session Token and retrieves the desired attachment through its Id on the database.
Note
You can download both individual attachments and folders. If the request points a folder, the API returns a .zip
archive with all the folder's attachments.
Note
In the request, the rk
is the parent key of the Master-Detail relation. rk
is optional in the request. You must specify rk
in the request if and only if you download an attachment from a Detail's row. Otherwise, the request refers to a row on the Master table.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/attachments/download |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | File Stream |
Examples¶
The method retrieves an attachment starting from the row's Id. In the example below, the method retrieves an attached XML file from a row.
Raw Request:
1 2 3 4 5 6 7 |
|
Raw Response:
1 2 3 4 5 |
|
Run Action¶
Data
The method launches one of the Custom Actions designed for the chosen application. The method identifies the Custom Action to launch through the action's actionId
.
Request¶
Method | POST |
URL | {base_url}/SmartExplorerApi/api/action/run |
Protocols | HTTPS |
ContentType | application/json |
Headers | ApplicationId, SessionToken, WorkspaceId |
Return | JSON Object |
Body:¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
Examples¶
The method executes the specified Custom Actions and returns the object reporting the operation's result. If the key IsSuccessful
in the object has value true
, the Custom Action has run successfully.
Raw Request:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Raw Response:
1 2 3 4 5 6 7 8 9 |
|
Send Email¶
Utility
The method queries the service to send an email containing the specified recipients, subject, body, and the providerId
(optional) in the request.
The providerId
is a GUID identifying an eLegere installation's email provider configured in the settings. If the request doesn't contain any providerId
, the Send Email API uses the default eLegere providerId configured during the installation.
Request¶
Method | POST |
URL | {base_url}/ewebaggregator/api/v1/email/queue |
Protocols | HTTPS |
ContentType | application/json |
Headers | Authorization, WorkspaceId |
Return | No Object Returned |
Body:¶
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Examples¶
The service receives the request with the recipients, subject, and the body information. In the example, the request doesn't contain a providerId
: it will use the default eLegere installation's provider.
Raw Request:
1 2 3 4 5 6 7 8 9 10 11 |
|
Raw Response:
1 |
|