RPC v1 and v2 Controllers description

application/src/main/java/org/thingsboard/server/controller/BaseController.java

@@ -157,6 +157,8 @@ public abstract class BaseController {
 
     public static final String CUSTOMER_ID = "customerId";
     public static final String TENANT_ID = "tenantId";
+    public static final String DEVICE_ID = "deviceId";
+    public static final String RPC_ID = "rpcId";
     public static final String ENTITY_ID = "entityId";
     public static final String ENTITY_TYPE = "entityType";
 
@@ -164,6 +166,7 @@ public abstract class BaseController {
             "The result is wrapped with PageData object that allows you to iterate over result set using pagination. " +
             "See the 'Model' tab of the Response Class for more details. ";
     public static final String DASHBOARD_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    public static final String RPC_ID_PARAM_DESCRIPTION = "A string value representing the rpc id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String DEVICE_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String DEVICE_PROFILE_ID_PARAM_DESCRIPTION = "A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
@@ -187,6 +190,7 @@ public abstract class BaseController {
 
     protected static final String ASSET_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the asset name.";
     protected static final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
+    protected static final String RPC_TEXT_SEARCH_DESCRIPTION = "Not implemented. Leave empty.";
     protected static final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
     protected static final String DEVICE_PROFILE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device profile name.";
     protected static final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer title.";
@@ -196,6 +200,7 @@ public abstract class BaseController {
     protected static final String SORT_PROPERTY_DESCRIPTION = "Property of entity to sort by";
     protected static final String DASHBOARD_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title";
     protected static final String CUSTOMER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, city";
+    protected static final String RPC_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, expirationTime, request, response";
     protected static final String DEVICE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, deviceProfileName, label, customerTitle";
     protected static final String DEVICE_PROFILE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, transportType, description, isDefault";
     protected static final String ASSET_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
@@ -205,6 +210,7 @@ public abstract class BaseController {
     protected static final String AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityType, entityName, userName, actionType, actionStatus";
     protected static final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
     protected static final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
+    protected static final String RPC_STATUS_ALLOWABLE_VALUES = "QUEUED, SENT, DELIVERED, SUCCESSFUL, TIMEOUT, EXPIRED, FAILED";
     protected static final String TRANSPORT_TYPE_ALLOWABLE_VALUES = "DEFAULT, MQTT, COAP, LWM2M, SNMP";
     protected static final String DEVICE_INFO_DESCRIPTION = "Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. ";
     protected static final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. ";

application/src/main/java/org/thingsboard/server/controller/EntityQueryController.java

@@ -681,8 +681,7 @@ public class EntityQueryController extends BaseController {
 
     private static final int MAX_PAGE_SIZE = 100;
 
-    @ApiOperation(value = "Count Entities by Query",
+    @ApiOperation(value = "Count Entities by Query", notes = ENTITY_COUNT_QUERY_DESCRIPTION)
-            notes = ENTITY_COUNT_QUERY_DESCRIPTION)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/entitiesQuery/count", method = RequestMethod.POST)
     @ResponseBody
@@ -697,8 +696,7 @@ public class EntityQueryController extends BaseController {
         }
     }
 
-    @ApiOperation(value = "Find Entity Data by Query",
+    @ApiOperation(value = "Find Entity Data by Query", notes = ENTITY_DATA_QUERY_DESCRIPTION)
-            notes = ENTITY_DATA_QUERY_DESCRIPTION)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/entitiesQuery/find", method = RequestMethod.POST)
     @ResponseBody
@@ -713,8 +711,7 @@ public class EntityQueryController extends BaseController {
         }
     }
 
-    @ApiOperation(value = "Find Alarms by Query",
+    @ApiOperation(value = "Find Alarms by Query", notes = ALARM_DATA_QUERY_DESCRIPTION)
-            notes = ALARM_DATA_QUERY_DESCRIPTION)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/alarmsQuery/find", method = RequestMethod.POST)
     @ResponseBody

application/src/main/java/org/thingsboard/server/controller/RpcV1Controller.java

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -38,17 +40,27 @@ import java.util.UUID;
 @Slf4j
 public class RpcV1Controller extends AbstractRpcController {
 
+    @ApiOperation(value = "Send one-way RPC request (handleOneWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead.")
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/oneway/{deviceId}", method = RequestMethod.POST)
     @ResponseBody
-    public DeferredResult<ResponseEntity> handleOneWayDeviceRPCRequest(@PathVariable("deviceId") String deviceIdStr, @RequestBody String requestBody) throws ThingsboardException {
+    public DeferredResult<ResponseEntity> handleOneWayDeviceRPCRequest(
+            @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
+            @PathVariable("deviceId") String deviceIdStr,
+            @ApiParam(value = "A JSON value representing the RPC request.")
+            @RequestBody String requestBody) throws ThingsboardException {
         return handleDeviceRPCRequest(true, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.REQUEST_TIMEOUT, HttpStatus.CONFLICT);
     }
 
+    @ApiOperation(value = "Send two-way RPC request (handleTwoWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead.")
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/twoway/{deviceId}", method = RequestMethod.POST)
     @ResponseBody
-    public DeferredResult<ResponseEntity> handleTwoWayDeviceRPCRequest(@PathVariable("deviceId") String deviceIdStr, @RequestBody String requestBody) throws ThingsboardException {
+    public DeferredResult<ResponseEntity> handleTwoWayDeviceRPCRequest(
+            @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
+            @PathVariable("deviceId") String deviceIdStr,
+            @ApiParam(value = "A JSON value representing the RPC request.")
+            @RequestBody String requestBody) throws ThingsboardException {
         return handleDeviceRPCRequest(false, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.REQUEST_TIMEOUT, HttpStatus.CONFLICT);
     }
 

application/src/main/java/org/thingsboard/server/controller/RpcV2Controller.java

@@ -15,6 +15,10 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -52,24 +56,88 @@ import static org.thingsboard.server.common.data.DataConstants.RPC_DELETED;
 @Slf4j
 public class RpcV2Controller extends AbstractRpcController {
 
+    private static final String RPC_REQUEST_DESCRIPTION = "Sends the one-way remote-procedure call (RPC) request to device. " +
+            "The RPC call is A JSON that contains the method name ('method'), parameters ('params') and multiple optional fields. " +
+            "See example below. We will review the properties of the RPC call one-by-one below. " +
+            "\n\n" + MARKDOWN_CODE_BLOCK_START +
+            "{\n" +
+            "  \"method\": \"setGpio\",\n" +
+            "  \"params\": {\n" +
+            "    \"pin\": 7,\n" +
+            "    \"value\": 1\n" +
+            "  },\n" +
+            "  \"persistent\": false,\n" +
+            "  \"timeout\": 5000\n" +
+            "}" +
+            MARKDOWN_CODE_BLOCK_END +
+            "\n\n### Server-side RPC structure\n" +
+            "\n" +
+            "The body of server-side RPC request consists of multiple fields:\n" +
+            "\n" +
+            "* **method** - mandatory, name of the method to distinct the RPC calls.\n" +
+            "  For example, \"getCurrentTime\" or \"getWeatherForecast\". The value of the parameter is a string.\n" +
+            "* **params** - mandatory, parameters used for processing of the request. The value is a JSON. Leave empty JSON \"{}\" if no parameters needed.\n" +
+            "* **timeout** - optional, value of the processing timeout in milliseconds. The default value is 10000 (10 seconds). The minimum value is 5000 (5 seconds).\n" +
+            "* **expirationTime** - optional, value of the epoch time (in milliseconds, UTC timezone). Overrides **timeout** if present.\n" +
+            "* **persistent** - optional, indicates persistent RPC. The default value is \"false\".\n" +
+            "* **retries** - optional, defines how many times persistent RPC will be re-sent in case of failures on the network and/or device side.\n" +
+            "* **additionalInfo** - optional, defines metadata for the persistent RPC that will be added to the persistent RPC events.";
+
+    private static final String ONE_WAY_RPC_RESULT = "\n\n### RPC Result\n" +
+            "In case of persistent RPC, the result of this call is 'rpcId' UUID. In case of lightweight RPC, " +
+            "the result of this call is either 200 OK if the message was sent to device, or 504 Gateway Timeout if device is offline.";
+
+    private static final String TWO_WAY_RPC_RESULT = "\n\n### RPC Result\n" +
+            "In case of persistent RPC, the result of this call is 'rpcId' UUID. In case of lightweight RPC, " +
+            "the result of this call is the response from device, or 504 Gateway Timeout if device is offline.";
+
+    private static final String ONE_WAY_RPC_REQUEST_DESCRIPTION = "Sends the one-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + ONE_WAY_RPC_RESULT;
+
+    private static final String TWO_WAY_RPC_REQUEST_DESCRIPTION = "Sends the two-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + TWO_WAY_RPC_RESULT;
+
+    @ApiOperation(value = "Send one-way RPC request", notes = ONE_WAY_RPC_REQUEST_DESCRIPTION)
+    @ApiResponses(value = {
+            @ApiResponse(code = 200, message = "Persistent RPC request was saved to the database or lightweight RPC request was sent to the device."),
+            @ApiResponse(code = 400, message = "Invalid structure of the request."),
+            @ApiResponse(code = 401, message = "User is not authorized to send the RPC request. Most likely, User belongs to different Customer or Tenant."),
+            @ApiResponse(code = 504, message = "Timeout to process the RPC call. Most likely, device is offline."),
+    })
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/oneway/{deviceId}", method = RequestMethod.POST)
     @ResponseBody
-    public DeferredResult<ResponseEntity> handleOneWayDeviceRPCRequest(@PathVariable("deviceId") String deviceIdStr, @RequestBody String requestBody) throws ThingsboardException {
+    public DeferredResult<ResponseEntity> handleOneWayDeviceRPCRequest(
+            @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
+            @PathVariable("deviceId") String deviceIdStr,
+            @ApiParam(value = "A JSON value representing the RPC request.")
+            @RequestBody String requestBody) throws ThingsboardException {
         return handleDeviceRPCRequest(true, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.GATEWAY_TIMEOUT, HttpStatus.GATEWAY_TIMEOUT);
     }
 
+    @ApiOperation(value = "Send two-way RPC request", notes = TWO_WAY_RPC_REQUEST_DESCRIPTION)
+    @ApiResponses(value = {
+            @ApiResponse(code = 200, message = "Persistent RPC request was saved to the database or lightweight RPC response received."),
+            @ApiResponse(code = 400, message = "Invalid structure of the request."),
+            @ApiResponse(code = 401, message = "User is not authorized to send the RPC request. Most likely, User belongs to different Customer or Tenant."),
+            @ApiResponse(code = 504, message = "Timeout to process the RPC call. Most likely, device is offline."),
+    })
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/twoway/{deviceId}", method = RequestMethod.POST)
     @ResponseBody
-    public DeferredResult<ResponseEntity> handleTwoWayDeviceRPCRequest(@PathVariable("deviceId") String deviceIdStr, @RequestBody String requestBody) throws ThingsboardException {
+    public DeferredResult<ResponseEntity> handleTwoWayDeviceRPCRequest(
+            @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
+            @PathVariable(DEVICE_ID) String deviceIdStr,
+            @ApiParam(value = "A JSON value representing the RPC request.")
+            @RequestBody String requestBody) throws ThingsboardException {
         return handleDeviceRPCRequest(false, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.GATEWAY_TIMEOUT, HttpStatus.GATEWAY_TIMEOUT);
     }
 
+    @ApiOperation(value = "Get persistent RPC request", notes = "Get information about the status of the RPC call.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/persistent/{rpcId}", method = RequestMethod.GET)
     @ResponseBody
-    public Rpc getPersistedRpc(@PathVariable("rpcId") String strRpc) throws ThingsboardException {
+    public Rpc getPersistedRpc(
+            @ApiParam(value = RPC_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable(RPC_ID) String strRpc) throws ThingsboardException {
         checkParameter("RpcId", strRpc);
         try {
             RpcId rpcId = new RpcId(UUID.fromString(strRpc));
@@ -79,16 +147,25 @@ public class RpcV2Controller extends AbstractRpcController {
         }
     }
 
+    @ApiOperation(value = "Get persistent RPC requests", notes = "Allows to query RPC calls for specific device using pagination.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/persistent/device/{deviceId}", method = RequestMethod.GET)
     @ResponseBody
-    public PageData<Rpc> getPersistedRpcByDevice(@PathVariable("deviceId") String strDeviceId,
+    public PageData<Rpc> getPersistedRpcByDevice(
-                                                 @RequestParam int pageSize,
+            @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION, required = true)
-                                                 @RequestParam int page,
+            @PathVariable(DEVICE_ID) String strDeviceId,
-                                                 @RequestParam RpcStatus rpcStatus,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
-                                                 @RequestParam(required = false) String textSearch,
+            @RequestParam int pageSize,
-                                                 @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
-                                                 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+            @RequestParam int page,
+            @ApiParam(value = "Status of the RPC", required = true, allowableValues = RPC_STATUS_ALLOWABLE_VALUES)
+            @RequestParam RpcStatus rpcStatus,
+            @ApiParam(value = RPC_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = RPC_SORT_PROPERTY_ALLOWABLE_VALUES)
+            @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
+            @RequestParam(required = false) String sortOrder) throws ThingsboardException {
         checkParameter("DeviceId", strDeviceId);
         try {
             TenantId tenantId = getCurrentUser().getTenantId();
@@ -100,10 +177,13 @@ public class RpcV2Controller extends AbstractRpcController {
         }
     }
 
+    @ApiOperation(value = "Delete persistent RPC", notes = "Deletes the persistent RPC request.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/persistent/{rpcId}", method = RequestMethod.DELETE)
     @ResponseBody
-    public void deleteResource(@PathVariable("rpcId") String strRpc) throws ThingsboardException {
+    public void deleteResource(
+            @ApiParam(value = RPC_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable(RPC_ID) String strRpc) throws ThingsboardException {
         checkParameter("RpcId", strRpc);
         try {
             RpcId rpcId = new RpcId(UUID.fromString(strRpc));

common/data/src/main/java/org/thingsboard/server/common/data/rpc/Rpc.java

@@ -16,6 +16,8 @@
 package org.thingsboard.server.common.data.rpc;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import org.thingsboard.server.common.data.BaseData;
@@ -24,15 +26,24 @@ import org.thingsboard.server.common.data.id.DeviceId;
 import org.thingsboard.server.common.data.id.RpcId;
 import org.thingsboard.server.common.data.id.TenantId;
 
+@ApiModel
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class Rpc extends BaseData<RpcId> implements HasTenantId {
+
+    @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
     private TenantId tenantId;
+    @ApiModelProperty(position = 4, value = "JSON object with Device Id.", readOnly = true)
     private DeviceId deviceId;
+    @ApiModelProperty(position = 5, value = "Expiration time of the request.", readOnly = true)
     private long expirationTime;
+    @ApiModelProperty(position = 6, value = "The request body that will be used to send message to device.", readOnly = true)
     private JsonNode request;
+    @ApiModelProperty(position = 7, value = "The response from the device.", readOnly = true)
     private JsonNode response;
+    @ApiModelProperty(position = 8, value = "The current status of the RPC call.", readOnly = true)
     private RpcStatus status;
+    @ApiModelProperty(position = 9, value = "Additional info used in the rule engine to process the updates to the RPC state.", readOnly = true)
     private JsonNode additionalInfo;
 
     public Rpc() {
@@ -53,4 +64,17 @@ public class Rpc extends BaseData<RpcId> implements HasTenantId {
         this.status = rpc.getStatus();
         this.additionalInfo = rpc.getAdditionalInfo();
     }
+
+    @ApiModelProperty(position = 1, value = "JSON object with the rpc Id. Referencing non-existing rpc Id will cause error.")
+    @Override
+    public RpcId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the rpc creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
 }