This section describes API calls that are not related to a specific model. The full URL would include the host name: http://[hostname].
The calls described here all contain /tool/ in the URL.
Other parameters are described with the relevant API call.
For an API call that carries out a search, a POST payload in JSON format is added.
Task |
Call |
URL |
Parameters |
Payload |
---|---|---|---|---|
Search |
POST |
/api/tool/Search/ |
format=json hierarchy=[hierarchy] |
{"query":"[query]"} |
The value of [query] follows Search syntax, for example:
{"query":"data/Countries with country_name contains King"}
The Request payload can also be a GET parameter, for example:
Task |
Call |
URL |
Parameters |
Response |
---|---|---|---|---|
Search |
GET |
/api/tool/Search/ |
format=json hierarchy=[hierarchy] query=[url_query] |
JSON format of the search result. |
The value of [url_query] is URL encoded string, for example:
data/Countries%20with%20country_name%20contains%20King
Furthermore, the meta property of the schema in the response to /api/tool/Search/ contain action details for the export of search results. This includes the URL for the data export POST request:
/api/export/export_data/?url=/api/tool/Search/
as well as the URL:
/api/view/ExportData/add
which has a schema that lists the data export data type choices that are used as a parameter to the POST call.
Two API calls are required.
Task |
Call |
URL |
Parameters |
Response |
---|---|---|---|---|
Submit file |
POST |
/api/ uploadfiles/ This URL will be moved to tool/UploadFile in future. |
hierarchy=[hierarchy] Content-Type: multipart/form-data name='uploadedfile' filename=<filename> the file to upload |
{"uploadedfiles": [{"id": "<file_id>", "name": "<filename>"}]} |
The response is HTTP 202
Task |
Call |
URL |
Parameters |
Payload |
---|---|---|---|---|
Bulk Load |
POST |
/api/tool/ BulkLoad/ |
method= bulkload_spreadsheet hierarchy=[hierarchy] |
Examples: {'bulkload_file': '<filename>', 'execute_immediately': true} or: {'bulkload_file': '<filename>', 'execute_immediately': false 'execute_date': '2013-06-20', 'execute_time': '12:00:00', 'execute_timezone': '0'} |
The following curl commands illustrate the two steps:
Step 1
curl -H 'Authorization: Basic <auth_key>' -F uploadedfile="@<file>.xlsx" 'http://<hostname>/api/uploadfiles/'
Step 2
curl -H 'Authorization: Basic <auth_key>' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary '{"bulkload_file":"DEMO.xlsx","execute_immediately":true}' 'http://<host>/api/tool/BulkLoad/?hierarchy=[hierarchy]& method=bulkload_spreadsheet& nowait=true& format=json'
The response to this call is for example as in the following table.
Response |
---|
{"href": "/api/tool/Transaction/0b340a6f-b658-48bb-ac8c-7562adc5572d", "success": true, "transaction_id": "0b340a6f-b658-48bb-ac8c-7562adc5572d"} |
If the Bulk Load is to be scheduled, the payload of the second task includes schedule details:
execute_immediately is set to false
execute_date is added in the format YYYY-MM-DD
execute_time is added in the format HH:MM:SS
execute_timezone is added in the format of a numeric value in minutes relative to UTC. For example, UTC is 0, UTC+2:00 is 120, UTC-1:00 is -60, and so on.
An entry is also generated in the schedule; that is, an instance is added to the data/Schedule module.
If the second task payload has 'execute_immediately': true, a POST is generated to /api/data/Bulkload/. The payload includes the uploaded filename and a generated name and time stamp as well as a description, for example:
{'filename': '<file>.xlsx', 'description': 'Generated by Bulk Loader Administration Tools', 'name': 'AnyUser.xlsx -- 2013-05-21 16:47:11.801664 (UTC)'}
To inspect the detailed progress and status of the transaction, use the API call from the response above:
GET /api/tool/Transaction/[pkid]
with parameters:
hierarchy=[hierarchy]
format=json
The response to this GET call is a JSON object that provides details of the transaction, as for example in the truncated snippet:
... "href": "/api/tool/Transaction/[pkid] "log_id": "53a8053ea616540708141f44", "message": "data_Countries_bulkloadsheet.xlsx is a valid "severity": "info", "time": "2014-06-23T10:45:18.029000", "transaction_id": "[pkid]" } ], "pkid": "[pkid]", "resource": {}, "rolled_back": "No", "started_time": "2014-06-23T10:45:17.813000", "status": "Success", "sub_transactions": [ { "action": "Execute Resource", "detail": "Execute : data_Countries_bulkloadsheet.xlsx -- ... "status": "Success", "submitted_time": "2014-06-23T10:45:19.567000", "transaction": "/api/tool/Transaction/[pkid1] ... }, { "action": "Create Schedule", "detail": "Name:data_Countries_bulkloadsheet.xlsx -- 2014- ... "status": "Success", "submitted_time": "2014-06-23T10:45:18.912000", "transaction": "/api/tool/Transaction/[pkid2] ... }, { "action": "Create Bulk Load", "detail": "Name:data_Countries_bulkloadsheet.xlsx -- 2014-06 ... "status": "Success", "submitted_time": "2014-06-23T10:45:18.419000", "transaction": "/api/tool/Transaction/[pkid3] ... } ], "submitted_time": "2014-06-23T10:45:17.794000",
The same transaction displays on the GUI.
For long transactions, to retrieve a summary of the status of the transaction, the transaction can be polled, using poll in the URL, using the same parameters:
GET /api/tool/Transaction/poll/?transactions=[pkid]
In this case, there is a shortened response, for example:
{"[pkid]": {"status": "Processing", "href": "/api/tool/Transaction/0b340a6f-b658-48bb-ac8c-7562adc5572d", "description": null} }