Here you will find infomation on how to call Cyclos services from 3rd party applications.
Cyclos 4 provides two distinct web service interfaces: the REST API (starting with version 4.6) and the WEB-RPC. In both interfaces the security layer is exactly the same (hence, both grant exactly the same permissions), and users are authenticated in the same way, as described below.
This API is implemented with REST concepts in mind, using JSON data for input and output, making it easier for developers to leverage existing knowledge when using it. It is documented using Swagger, which is the base for Open API. A detailed reference documentation is available online on each Cyclos installation, at <cyclos-root-url>[/network]/api. For example, the Cyclos Demo API is available at http://demo.cyclos.org/api. It is possible to disable the API reference documentation page by setting cyclos.rest.reference = false in cyclos.properties.
The REST API contains a subset of the Cyclos functionality. New functionality will be added on demand, in a cautious manner, as each path, parameter and data model needs to be planned to fit the target architecture. This is the preferred interface for clients to connect to Cyclos, as it should be stable between Cyclos releases, and provides better documentation and tooling support, as Swagger provides tools, for example, to generate clients for distinct languages / frameworks.
The WEB-RPC provides access to the entire service layer in Cyclos 4. It is, for example, used by the main Cyclos web application. The available services are linked here. This page also links to the changes between each Cyclos 4 release. As the service layer is exported directly, it tends to contain more changes between releases than the REST interface.
The WEB-RPC also uses JSON objects for input / output, and provides, besides plain HTTP calls, a Java and a PHP client libraries.
Regardless the web service interface (REST or WEB-RPC), users are authenticated either as user / password (stateless), logging-in with a session (stateful) or using access clients (stateless). The way authentication data is passed from client to server depends on whether the clients are using the Java API, the PHP API or WEB-RPC calls.
In this mode, a principal (user identification method), which can be the login name, e-mail, mobile phone, custom field, account number or token value (card number), depending on the channel configuration, is sent on each request together with the password (live systems should be over HTTPS, so should be secure). The drawback is that the username and password need to be stored in the client application, and changing the password on the web (if the same password type is used) will make the application stop working.
In this mode, a first request is made to LoginService.login() operation, returning a session token. Subsequent requests should pass this session token instead in the subsequent requests. Notice that the first request should be authenticated with user and password. To finish a session, a request to LoginService.logout() using the session token invalidates the session.
Access clients can be configured to prevent the login name and password to be passed on every request by clients, decoupling them from the actual user password, which can then be changed without affecting the client access, and improving security, as each client application has its own authorization token.
To configure access clients, first a new identification method of thist type must be created by administrators. Then, in a member product of users which can use this kind of access, permissions over that type should be granted. Finally, the user (or an admin) should create a new access client in Cyclos main access, and get the activation code for it. The activation code is a short (4 digits) code which uniquely identifies an access client pending activation for a given user. To use the access client, on the application side (probably a server-side application or an interactive application), an HTTP POST request should be performed, with the following characteristics:
The result will be a token which should be passed in requests. The activation process should be done only once, and the token will be valid until the access client in Cyclos is blocked or disabled.
Here is an example which can be called by the command-line program curl:
curl http[s]://<cyclos-root-url>[/network]/activate-access-client \
-u "<username>:<password>"
-d "<4-digit code>"The generated token will be printed on the console, and should be stored on the client application to be used on requests.
Additionally, clients can improve security if they can have some unique identifier which can be relied on, and don't need to be stored. For example, Android devices always provide an unique device identifier. In that case, this identification string can be passed on the moment of activation, and will be stored on the server as a prefix to the generated token. The server will return only the generated token part, and this prefix should be passed on requests together with the generated token. The prefix is passed in the activation command, having the body of the request as: [4-digit activation code]:prefix. So, for example:
curl https://www.some-cyclos-instance.com/activate-access-client \
-u "john:johnpassword"
-d "1234:XYZW"Imagining the server returns the fictional token ABCDEFG (the actual token is 64 characters long), the token to be used on requests would be XYZWABCDFG.
Alternatively, it is possible to do a request authenticated by username and password to the AccessClientService.activate() web service method, passing the activation code and prefix parameters. This can be more convenient for client applications that activate an access client interatively, for example, when the end user types in his username, password and 4-digit activation code.
Channels can be seen as a set of configurations for an access in Cyclos. There are some built-in channels, and additional ones can be created. The built-in channels are:
By default, the channel used on any web service (regardless the interface or user authentication mode) is "Web services". It is possible to specify another channel, for example, with third party web applications (handled as Main web) or third party mobile applications. In such cases, the channel internal name must be passed on each request, but the specific way to pass it depends on whether client is using REST / WEB-RPC, Java API or PHP API.