Sugar Labs

Sugar Network/API: Difference between revisions

← Older editNewer edit →
Line 62: Line 62:
List of actions common of all resources.
List of actions common of all resources.


  '''POST''' /<RESOURCE>
  '''POST''' /''RESOURCE''


Create new resource object.
Create new resource object.


Dictionary to send:
JSON object keys to send:
: {{Code|''RESOURCE}}'s properties.
* {{Code|''RESOURCE}}'s properties.


Dictionary keys to receive:
JSON object keys to receive:
:* {{Code|guid}}, with globally unique identifier that specifies created object.
* {{Code|guid}}, with globally unique identifier that specifies created object.


  '''PUT''' /<RESOURCE>/<GUID>
  '''PUT''' /''RESOURCE''/''GUID''


Modify resource object. By default, might be called only by {{Code|GUID}} creator.
Modify resource object. By default, might be called only by {{Code|GUID}} creator.


Dictionary to send:
JSON object keys to send:
: {{Code|RESOURCE}}'s properties to modify.
* {{Code|RESOURCE}}'s properties to modify.


  '''DELETE''' /<RESOURCE>/<GUID>
  '''DELETE''' /''RESOURCE''/''GUID''


Delete resource object. The real destroying won't happen, the object will be hidden. The garbage collection of hidden objects will be processed by Network administrators. By default, might be called only by {{Code|GUID}} creator.
Delete resource object. The real destroying won't happen, the object will be hidden. The garbage collection of hidden objects will be processed by Network administrators. By default, might be called only by {{Code|GUID}} creator.


  '''GET''' /<RESOURCE>?offset=<INTEGER>&limit=<INTEGER>[&query=<STRING>][&reply=<PROP>[,..]][&order_by=<nowiki>[+|-]</nowiki><PROP>][&group_by=<PROP>][&<QUERY_PROP>=<VALUE>[&...]]
  '''GET''' /''RESOURCE''[?offset=''INTEGER''][&limit=''INTEGER''][&query=''STRING''][&reply=''PROP''[,..]][&order_by=<nowiki>[+|-]</nowiki>''PROP''][&group_by=''PROP''][&''QUERY_PROP''=''VALUE''[&...]]


Find resource objects.
Find resource objects.


Where:
Where:
:* {{Code|offset}}, ''int''<br>start index to return entries from;
* {{Code|offset}}, ''int''<br>start index to return entries from;
:* {{Code|limit}}, ''int''<br>do not return more then specified value;
* {{Code|limit}}, ''int''<br>do not return more then specified value;
:* {{Code|query}}, ''str''<br>search request in [http://xapian.org/docs/queryparser.html Xapian] notation with the following additions:
* {{Code|query}}, ''str''<br>search request in [http://xapian.org/docs/queryparser.html Xapian] notation with the following additions:
:** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|<PROP>:[<START>]..[<END>]}};
** if property is boolean, integer or datetime, it supports searching by ranges: {{Code|''PROP'':[''START'']..[''END'']}};
:** the statement {{Code|<nowiki><PROP>:=["]<VALUE>["]</nowiki>}} means {{Code|(<THE-REST_QUERY>) AND <EXACT-PROP-SEARCH>}} with searching {{Code|PROP}} for exact {{Code|VALUE}}; it is different to regular {{Code|<PROP>:<VALUE>}} where {{Code|VALUE}} might be a substring of exact {{Code|PROP}} value;
** the statement {{Code|''PROP''<nowiki>:=</nowiki>["]''VALUE''["]}} has the same effect as {{Code|QUERY_PROP}}; it is different to regular {{Code|''PROP'':''VALUE''}} where {{Code|VALUE}} might be a substring;
:* {{Code|QUERY_PROP}}, ''str''<br>supplement {{Code|query}} with filtering by property value, the resulting query string will be {{Code|<nowiki>QUERY_PROP=VALUE AND (query)</nowiki>}};
* {{Code|QUERY_PROP}}, ''str''<br>supplements {{Code|query}} with filtering by exact value of the {{Code|QUERY_PROP}}; the resulting query string will be {{Code|''QUERY_PROP''<nowiki>=</nowiki>''VALUE'' AND (query)}};
:* {{Code|reply}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return only {{Code|guid}} property;
* {{Code|reply}}, ''str''<br>coma separated list of ''RESOURCE'' properties to return; by default, return only {{Code|guid}} property;
:* {{Code|order_by}}, ''str''<br>property to sort the resulting list by; if starts with the {{Code|-}}, the order is descending, otherwise it is ascending;
* {{Code|order_by}}, ''str''<br>property to sort the resulting list by; if starts with the {{Code|-}}, the order is descending, otherwise it is ascending;
:* {{Code|group_by}}, ''str''<br>property name to group resulting list by.
* {{Code|group_by}}, ''str''<br>property name to group resulting list by.


Dictionary keys to receive:
JSON object keys to receive:
:* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
* {{Code|total}}, total number in requested query (the reply might contain only portion restricted by {{Code|limit}} request argument);
:* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.
* {{Code|result}}, an array of dictionaries with resource object properties, dictionaries contain at least {{Code|guid}} property.


  '''GET''' /<RESOURCE>/<GUID>[?reply=<PROP>[,..]]
  '''GET''' /''RESOURCE''/''GUID''[?reply=''PROP''[,..]]


Return properties for particular resource object.
Return properties for particular resource object.


Dictionary keys to receive:
JSON object keys to receive:
:* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.
* properties that were specified in {{Code|reply}} argument(s), at least {{Code|guid}}.


  '''GET''' /<RESOURCE>/<GUID>/<PROPERTY>
  '''GET''' /''RESOURCE''/''GUID''/''PROP''


Return property value for particular resource object.
Return property value for particular resource object.


Data to receive:
Data to receive:
:* property value in JSON notation.
* property value in JSON notation for regular properties;
* raw data or redirection for BLOB properties.


=== Download activities ===
=== Download activities ===
Retrieved from "https://wiki.sugarlabs.org/go/Sugar_Network/API"