The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
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 will be 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} }