From SysOrb version 4.2 a RESTfull API is shipped with SysOrb. The API allows integrating SysOrb with 3rd party services or extends its functionality. This chapter provides documentation of how to use SysOrb RESTfull API..
REST - Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used.
Web server - Web server can refer to either the hardware (the computer) or the software (the computer application) that helps to deliver Web content that can be accessed through the Internet.
Authentication - is the process of determining whether someone or something is, in fact, who or what it is declared to be.
Authorization - function of specifying access rights to resources
CRUD - create, read, update and delete (CRUD) are the four basic functions of persistent storage.
URI - A URI identifies a resource either by location or name. More often than not, most of us use URIs that defines a location to a resource. However, a URI does not have to specify the location of a specific representation.
URL - A URL is a URI but a URI is not a URL. A URL is a specialization of URI that defines the network location of a specific representation for a given resource.
In addition to standard Web browser interface SysOrb will expose its subset of its functionality via RESTful API accessible via HTTP(S) transport. API operations will be invoked at specific server endpoints (HTTP resources).
All API requests are completely independent from each other, i.e. we don't maintain any session specific state machine on server - that is an essence of REST approach. The duty of maintaining the state of session (if needed) lies on client. For example, in order to match the state before request send to server and after getting a response, the client can send some context specific information (cookie) related to request and server, after processing the request returns response as well as unmodified context data (cookie, etc) attached to request.
Another distinct feature of REST approach that should be supported by SysOrb Web API is "CRUD" approach to accessing the data that matches to standard HTTP methods: Create=POST, Read=GET, Update=PUT, Delete=Delete.
Thus, using this approach, the majority of requests will work with server as with data storage. In some the cases when some procedure needs to be invoked on SysOrb server (like "rescan") - POST request (with arguments if needed) will be sent to corresponding endpoint.
Initial vision on SysOrb Web API implementation is to make as simple bridge to access SysOrb database via HTTP+XML, i.e. don't make significant data post processing/aggregation (like standard CGI of Web interface does). However, provisions should be made in API implementation to have the possibility for creating complex responses (combined from several data sources).
All the communication with users of the API (either mobile clients or other servers) will done via standard HTTP(S) protocol.
"sysorb-webapi" module is the main point for accepting requests, parsing them, querying data from one of SysOrb databases, preparing response and sending it back to client
Designed and developed "sysorb-webapi" module (executable) is expected to be the main outcome of this specification.
Sysorb-webapi should be started by sysorbd continue running together with other sysorb processes (like sysorb-dbms, sysorb-tsdb).
For communication with SysOrb databases sysorb-webapi will use the same shared memory based IPC protocol (see sibling manager) that is used by other SysOrb processes.
XML is used for data transferred via HTTP.