5,705
edits
Changes
no edit summary
To better understand this API, see a technical explanation of its [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[#Sugar_Network_resources|objects model]] in particular.
To better understand this API, see a technical explanation of its [[Platform_Team/Sugar_Network/Architecture#Conceptual_level|conceptual level]] and [[#Sugar_Network_resources|objects model]] in particular.
The API operates with [[Sugar Network]] [[#Sugar_Network_resources|resources]], which are collections of objects. All objects are identified by globally unique identifiers, GUIDs. Resources might support [[#Common_actions|common actions]]. While processing requests, the server might generate [[#Notifications|events]].
The API operates with [[Sugar Network]] [[#Sugar_Network_resources|resources]], which are collections of objects. All objects are identified by globally unique identifiers, GUIDs, and available for operation via [[#Base_API|basic actions]]. The API is being provided from a [[#API_servers|node server]] or a [[#Client_API|client]]. While processing requests, API providers generate [[#Notifications|events]].
The API is [[Wikipedia:Restful|RESTful]], and is served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common RESTful request url format is:
The API is [[Wikipedia:Restful|RESTful]], and is served via HTTP(S) using [[Wikipedia:Json|JSON]] notation. The common RESTful request url format is:
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
* {{Code|ARGUMENT}}s and {{Code|VALUE}}s depend on the particular [[#Actions|action]].
In [[#Common_actions|most cases]], the server replies in JSON notation. If a request fails, the replied JSON object will contain a {{Code|request}} key, with the original request, and {{Code|error}} key, with an error message.
In most cases, the server replies in JSON notation. If a request fails, the replied JSON object will contain a {{Code|request}} key, with the original request, and {{Code|error}} key, with an error message.
== API servers ==
== API servers ==
{{:Sugar_Network/Resources}}
{{:Sugar_Network/Resources}}
== Nodes ==
== Base API ==
List of actions common of all API providers.
List of actions common of all resources.
<div id="POST"></div>
<div id="POST"></div>
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
Delete existing aggregated item. Depending on particular property, the command is allowed either to object's authors or to aggregated item submitter.
=== Notifications ===
It is possible to subscribe to server events. Notification will happen using HTML5 [[wikipedia:Server-sent_events|Server-sent events]] (SSE).
To start subscription, send the following request:
'''GET''' /?cmd='''subscribe'''
Response will be served with ''text/event-stream'' MIME type for default SSE message type. SSE message will be a JSONified object with the following, at least, attributes:
* {{Code|event}}<br>event type.
== Node API ==
This is an API provided by Sugar Network nodes on top of [[#Base_API|base API]].
=== Authentication ===
Right now, the only way to be authenticated on a Sugar Network server is by running a [[Platform_Team/Sugar_Network/Implementation#sugar-network-client|local application]] on the client side and using the API it [[#Client_proxy|provides]].
''TODO''
=== Authorization ===
Read-only access is available for anonymous requests, except special content like machine serial numbers. But to process any changes, clients need to be authenticated.
Right after creating any Sugar Network object, its author becomes the only user who can process any object modifications afterwards. Authority information will be kept in the [[#Sugar_Network_resources|author]] property and can be modified using the following commands.
'''PUT''' /''RESOURCE''/''GUID''?cmd='''useradd'''&user=''USER''&role=''ROLE''
Add another user who can modify the corresponding object. ''USER'' argument should be either ''User'' guid (for authors registered in the Sugar Network), or, full author name.
'''PUT''' /''RESOURCE''/''GUID''?cmd='''userdel'''&user=''USER''
Remove user from the authority list. It is not possible to remove yourself. ''USER'' argument should be either ''User'' guid (for authors registered in the Sugar Network), or, full author name.
''TODO''
=== Download releases ===
=== Download releases ===
* Arbitrary data,<br>all required release properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing releases to pickup license from.
* Arbitrary data,<br>all required release properties should be specified in {{Code|PROP}} arguments, at least ''context'' and ''version''; ''license'' should be specified only if there are no existing releases to pickup license from.
=== Node statistics ===
=== Node statistics ===
* {{Code|source}}, multiple argument to specify what [[Sugar_Network/Node_Statistics#Common_statistics|stats]] should be returned.
* {{Code|source}}, multiple argument to specify what [[Sugar_Network/Node_Statistics#Common_statistics|stats]] should be returned.
== Client proxy ==
== Client API ==
The reasons to proxy Sugar Network data on users side:
The reasons to proxy Sugar Network data on users side:
=== Offline mode ===
=== Offline mode ===
Being connected to a Sugar Network server, local proxy provides original Sugar Network content. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working. Any content created in offline mode will be uploaded to the server after getting a connection back.
Being connected to a Sugar Network node, local proxy provides [[#Node_API|original API]] from the node. If the connection is lost, the proxy will switch to local Sugar Network storage and continue working providing only [[#Base_API|base API]]. Any content created in offline mode will be uploaded to the node after getting a connection back.
Besides, local Sugar Network storage will be reused to keep users preferences, such as:
Besides, local Sugar Network storage will be reused to keep users preferences, such as: