RESTful API¶
Catalog and Data Store¶
The Catalog and Data Store are using the same logic and syntax for access and query language. The database which holds the information is MongoDB. MongoDB is a schemaless document noSQL database. The query language that the API deploys is the json representation of MongoDB.
API Return Data Structure¶
The API returns data in a consistent structure.
count: number if result records returned
meta: page, page_size, pages
next and previous: urls to page through data
results: list of records return from API
{ "count": 1, "meta": { "page": 1, "page_size": 50, "pages": 1 }, "next": null, "previous": null, "results": [ ] }
URL Parameters¶
page_size:¶
The page_size returns the available records up to page_size. If more records exist, the next url value will be deployed.
?page_size=100
?page_size=0
If page_size=0 API will return all records.
page:¶
The page variable will move to the page requested. If the page does not exist the last page will be shown.
format:¶
api (Default) - Return type is HTML format
json - Return type is JSON format
jsonp - Return type is JSONP format
xml - Return type is xml format
?format=json
query:¶
The query url parameter is a JSON format query language. Please see below
Query Language¶
The API query language is based from the MongoDB pyhton query syntax.
Create Database and Collections¶
Create Database¶
View: /api/data_store/data/ HTTP Request: Post
Data: {"database":"mydata"} Format: JSON
Delete Database¶
View: /api/data_store/data/ HTTP Request: Post
Data: {"action":"delete","database":"mydata"} Format: JSON
Create Collection¶
View: /api/data_store/data/mydata HTTP Request: Post
Data: {"collection":"mycollection"} Format: JSON
Delete Collection¶
View: /api/data_store/data/mydata HTTP Request: Post
Data: {"action":"delete","collection":"mycollection"} Format: JSON
Filter Query¶
The following examples are on the collection view.
Filter Query¶
?query={"filter":{"tag":"content"}}
?query={"filter":{"tag":"content","tag2":"content"}}
# Return fields (projection: 0,1)
?query={"filter":{"tag":"content","tag2":"content"},"projection":{"tag":0}
Distinct Query¶
?distinct=tag,tag2
# Include query parameter
?distinct=tag&query={"filter":{"department":"Informatics"}}
MongoDb Aggregation¶
Please refer to MongoDB Documentation
?aggregate=[{"$match":{"status": "urgent"}},
{"$group":{"_id":"$productName","sumQuantity":{"$sum":"$quantity"}}}]
Task Execution (celery)¶
The Celery Distributed Task Queue is integrated throught the RESTful API.
List of Available Tasks and Task History¶
URL: /api/queue/
Task History: /api/queue/usertasks/
Task Submission¶
Example:
URL /api/queue/run/cybercomq.tasks.tasks.add/
Docstring: Very import to give users the description of task.
Curl Example: Comand-line example with API token
Task HTML POST Data Requirement¶
{
"function": "cybercomq.tasks.tasks.add",
"queue": "celery",
"args": [],
"kwargs": {},
"tags": []
}
function: task name queue: which queue to route the task args: [] List of argument kwargs: {} Keyword arguments tags: [] list of tags that will identify task run
Curl Command - Command-line Scripting¶
curl -X POST --data-ascii '{"function":"cybercomq.tasks.tasks.add","queue":"celery","args":[],"kwargs":{ },"tags": []}' http://localhost/api/queue/run/cybercomq.tasks.tasks.add/.json -H Content-Type:application/json -H 'Authorization: Token < authorized-token > '
Python Script to Execute Script¶
import requests,json
headers ={'Content-Type':'application/json',"Authorization":"Token < authorized token >"}
data = {"function":"cybercomq.tasks.tasks.add","queue":"celery","args":[2,2],"kwargs":{},"tags":["add"]}
req=requests.post("http://localhost/api/queue/run/cybercomq.tasks.tasks.add/.json",data=json.dumps(data),headers=headers)
print(req.text)
Javascript JQuery $.postJSON¶
//postJSON is custom call for post to cybercommons api
$.postJSON = function(url, data, callback,fail) {
return jQuery.ajax({
'type': 'POST',
'url': url,
'contentType': 'application/json',
'data': JSON.stringify(data),
'dataType': 'json',
'success': callback,
'error':fail,
'beforeSend':function(xhr, settings){
xhr.setRequestHeader("X-CSRFToken", getCookie('csrftoken'));
}
});
}