Besides using the URL pointing to the service, and have the POST body as a JSON, selecting the operation and the parameters, it is also possible to choose the operation in the URL itself, as a subpath in the URL. For example, https://my.cyclos.instance.com/network/web-rpc/userService/search already maps to the search operation. The POST body, then, is expected to be just the JSON for the parameters, with the same rules as explained above: if is a single parameter, the body can be the JSON value directly, and if no parameters, the POST body can be empty.

Additionally, the service methods that are readonly can be invoked by GET requests. In this case, the parameter can be passed using 2 forms:

Finally, services are mapped to other 2 URLs besides <name>Service: one without the 'Service' suffix, and another one, pluralized. Also, if an operation doesn't match, it will be attempted by prepending 'get' with the first letter capitalized. This will allow shorter urls on calls, like:

All output objects, when converted to JSON, will have a property called class, which represents the fully-qualified Java class name of the source object. Most clients can just ignore the result. However, when sending requests to classes that expect a polymorphic object, the server needs to know which subclass the passed object represents. In those cases, passing the class property, with the fully qualified Java class name is required. An example is the AdService. When saving an advertisement, it could either be a simple advertisement (AdvertisementDTO) or a webshop advertisement (AdWebShopDTO). In this case, a class property with the fully qualified class name is required. Note, however, that in most cases, the class information is not needed.

Whenever a subclass of EntityVO is needed, numbers or strings are also accepted (besides objects). Numbers always represent the vo identifier (id property). Strings can either be id when they are numeric, or can represent one of the following cases:

If the value is supposed to be a number handled as user principal (for example, a mobile phone) or account number, it must be prefixed with a single quote. For example, to represent a phone number as string, the following is accepted: '5187653456. If not prefixed, it would be interpreted as user id instead. The single quote prefix is the same as Excel / LibreOffice use to represent a number as string.

Other points to note with JSON handling:

Assuming that the authentication header is correctly passed, the following request can be performed to search for users: POST https://my.cyclos.instance.com/network/web-rpc/userService with the following body:

{
    "operation": "search",
    "params": {
        "keywords": "user",
        "groups": "consumers",
        "pageSize": 5
    }
}

The resulting JSON will be something like:

{
    "result": {
        "currentPage": "0",
        "pageSize": "40",
        "totalCount": "2",
        "pageItems": [
            {
                "class": "org.cyclos.model.users.users.UserDetailedVO",
                "id": "-2717327251475675143",
                "display": "Consumer 1",
                "shortDisplay": "c1"
            },
            {
                "class": "org.cyclos.model.users.users.UserDetailedVO",
                "id": "-2717467988964030471",
                "display": "Consumer 3",
                "shortDisplay": "c3"
            }
        ]
    }
}

Note the params "groups" property of the input query is a collection of BasicGroupVO. It is being passed the string "consumers", which is matched to the group internal name.

The above request is equivalent to a POST to https://my.cyclos.instance.com/network/web-rpc/users/search (using the plural name) with the following body:

{
    "keywords": "user",
    "groups": "consumers",
    "pageSize": 5
}

Note only the parameters part is passed. If the service method would require multiple parameters, the body should be a JSON array. If a single string, the string should be quoted, just like in JSON.

Also, the above request is equivalent to a GET to https://my.cyclos.instance.com/network/web-rpc/user/search?keywords=user&groups=consumers&pageSize=5 (singular name). Only methods which take a single parameter object can use query parameters.