4.8.1.2.10. Service Calls

Service methods available for API calls are listed in a configuration file. The name of the file is defined by the cuba.restServicesConfig property.

A sample REST API services configuration file:

<services xmlns="http://schemas.haulmont.com/cuba/restapi-service-v2.xsd">
    <service name="refapp_PortalTestService">
        <method name="findAllCars"/>
        <method name="updateCarVin"/>
    </service>
</services>

Service method call can be performed both by GET and POST requests. Additionally, POST requests allow passing entities or entity collections to the invoked method.

Service Call by GET Request

Request format:

{host:port}/app-portal/api/service.<format>?service=<serviceName>&method=<methodName>&view=<view>&param0=<value 0>&paramN=<value N>&param0_type=<type 0>&paramN_type=<type N>&s=<sessionId>

  • format - defines the output format. Two values are accepted: xml or json.

  • service - the name of the service called.

  • method - the name of the method invoked.

  • param0 .. paramN - parameter values of the method.

  • param0_type .. paramN_type - parameter types of the method.

  • s - the current session identifier.

If a service has a single method with the specified name and number of parameters, explicit parameter type definition is not required. In other cases, parameter type must be specified.

Service Call by POST Request

Request format:

{host:port}/app-portal/api/service?s=<sessionId>

  • s - the current session identifier.

JSON or XML with the description of the method call is passed in the request body.

JSON format

The Content-Type header value is application/json.

{
  "service": "refapp_PortalTestService",
  "method": "updateCarVin",
  "view": "carEdit",
  "params": {
    "param0": {
      "id": "ref$Car-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
      "vin": "WV00001",
      "colour" : {
        "id": "ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7",
        "name": "Red"
      },
      "driverAllocations": [
        {
          "id": "ref$DriverAllocation-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
        },
        {
          "id": "NEW-ref$DriverAllocation"
        }
      ]
    },
    "param1": "WV00001",
    "param0_type": "com.haulmont.refapp.core.entity.Car",
    "param1_type": "java.lang.String"
  }
}

Properties of the passed object:

  • service - the name of the service called.

  • method - the name of the method invoked.

  • param0 .. paramN - method parameter values.

  • param0_type .. paramN_type - method parameter types.

XML format

The Content-Type header value is text/xml.

<ServiceRequest xmlns="http://schemas.haulmont.com/cuba/restapi-service-v2.xsd">
    <service>refapp_PortalTestService</service>
    <method>updateCarVin</method>
    <view>carEdit</view>
    <params>
        <param name="param0">
            <instance id="ref$Car-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab">
                <field name="vin">WV00000</field>
                <reference name="colour">
                    <instance id="ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7">
                        <field name="name">Red</field>
                    </instance>
                </reference>
                <collection name="driverAllocations">
                    <instance id="ref$DriverAllocation-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"/>
                    <instance id="NEW-ref$DriverAllocation"/>
                </collection>
            </instance>
        </param>
        <param name="param1">WV00001</param>
        <param name="param0_type">com.haulmont.refapp.core.entity.Car</param>
        <param name="param1_type">java.lang.String</param>
    </params>
</ServiceRequest>

The main elements of the passed document are:

  • service - the name of the service called.

  • method - the name of the method invoked.

  • param - the value of the parameter method or the parameter type. The name of the parameter (name attribute) must have the format param0 .. paramN or param0_type .. paramN_type.

If a service has a single method with the specified name and number of parameters, explicit parameter type definition is not required. In other cases, parameter types must be specified.

<param> element may contain both plain text (for setting primitive type values) and nested <instance> elements for entities or <instances> for entity collections.

The XSD of the request is available at http://schemas.haulmont.com/cuba/6.4/restapi-service-v2.xsd.

Supported Service Method Parameter Types

  • primitive Java types. long, int, boolean, etc. should be specified as the type name.

  • primitive Java type wrappers. The full class name should be specified as the type name: java.lang.Boolean, java.lang.Integer, etc.

  • string (java.lang.String).

  • date (java.util.Date).

  • UUID (java.util.UUID).

  • BigDecimal (java.math.BigDecimal)

  • entity (for POST requests only). The full class name should be specified as the type name, e.g. com.haulmont.cuba.security.entity.User.

  • entity collections (for POST requests only). The full class or collection interface name should be specified as the type name, e.g. java.util.List.

Service Call Result

The result may be in JSON or XML, depending on the method call declaration. Currently, methods can return primitive data types, entities and entity collections.

Example of a JSON result

Primitive data type:

{
  "result": "10"
}

Entity:

{
  "result": {
    "id" : "ref$Colour-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
    "name": "Red"
  }
}
Example of XML result

Primitive data type:

<result>
    10
</result>

Entity:

<result>
    <instance id="ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7">
        <field name="name">Red</field>
    </instance>
</result>

The XSD of the result is available at http://schemas.haulmont.com/cuba/6.4/restapi-service-v2.xsd.