inosh
/
device-mgt-core
forked from community/device-mgt-core
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

swagger annotations and definition update continued for device type, device, policy, role, user, group and user management.

Browse Source
4.x.x
Shavindri 8 years ago
parent 7d7977cbdc
commit 0842dcb2bb
10 changed files with 441 additions and 377 deletions
Show Stats Download Patch File Download Diff File

59
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/ActivityInfoProviderService.java
Unescape View File

@ -47,14 +47,14 @@ public interface ActivityInfoProviderService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Retrieve details of a particular activity.", value = "Getting Details of an Activity",
notes = "This will return information of a particular activity i.e. meta information of an operation, " + notes = "Retrieve the details of a specific activity/operation, such as the meta information of an operation, " +
"etc; including the responses from the devices.", "including the responses from the devices.",
tags = "Activity Info Provider") tags = "Activity Info Provider")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Activity details are successfully fetched", message = "OK. \n Successfully fetched the activity details.",
response = Activity.class, response = Activity.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -66,13 +66,12 @@ public interface ActivityInfoProviderService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
@ -82,28 +81,31 @@ public interface ActivityInfoProviderService {
message = "Unauthorized. \n Unauthorized request."), message = "Unauthorized. \n Unauthorized request."),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n No activity is found under the provided id.", message = "Not Found. \n No activity found with the given ID.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching activity data.", message = "Internal Server Error. \n Server error occurred while fetching the activity data.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view")
Response getActivity( Response getActivity(
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "Activity id of the operation/activity to be retrieved.", value = "Activity id of the operation/activity.",
required = true) required = true,
defaultValue = "ACTIVITY_1")
@PathParam("id") @PathParam("id")
@Size(max = 45) @Size(max = 45)
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time\n." +
"Provide the value in the Java Date Format: EEE, d MMM yyyy HH:mm:ss Z\n." +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String ifModifiedSince); @HeaderParam("If-Modified-Since") String ifModifiedSince);
@ -112,14 +114,13 @@ public interface ActivityInfoProviderService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Retrieve details of a particular activity.", value = "Getting Activity Details",
notes = "This will return information of a particular activities i.e. meta information of operations, " + notes = "Get the details of the operations/activities executed by the server on the devices registered with WSO2 EMM, during a defined time period.",
"etc; including the responses from the devices which happened after given time.",
tags = "Activity Info Provider") tags = "Activity Info Provider")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Activity details are successfully fetched", message = "OK. \n Successfully fetched the activity details.",
response = ActivityList.class, response = ActivityList.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -131,13 +132,12 @@ public interface ActivityInfoProviderService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 401, code = 401,
message = "Unauthorized. \n Unauthorized request."), message = "Unauthorized. \n Unauthorized request."),
@ -150,30 +150,35 @@ public interface ActivityInfoProviderService {
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching activity data.", message = "Internal Server Error. \n Server error occurred while fetching the activity data.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Activities", permission = "/device-mgt/devices/owning-device/view")
Response getActivities( Response getActivities(
@ApiParam( @ApiParam(
name = "since", name = "since",
value = "Validates if the requested variant has not been modified since the time specified, this " + value = "Checks if the requested variant was created since the specified date-time.\n" +
"should be provided in unix format in seconds.", "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@QueryParam("since") String since, @QueryParam("since") String since,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many activity details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") int limit, @QueryParam("limit") int limit,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time\n." +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n." +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String ifModifiedSince); @HeaderParam("If-Modified-Since") String ifModifiedSince);

243
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceManagementService.java
Unescape View File

@ -52,8 +52,8 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the list of devices enrolled with the system.", value = "Getting Details of Registered Devices",
notes = "Returns all devices enrolled with the system.", notes = "Provides details of all the devices enrolled with WSO2 EMM.",
tags = "Device Management") tags = "Device Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse(code = 200, message = "OK. \n Successfully fetched the list of devices.", @ApiResponse(code = 200, message = "OK. \n Successfully fetched the list of devices.",
@ -68,25 +68,23 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "The incoming request has more than one selection criteria defined through query" + message = "The incoming request has more than one selection criteria defined via the query parameters.",
" parameters.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "No device is currently enrolled with the server.", message = "The search criteria did not match any device registered with the server.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the device list.", message = "Internal Server Error. \n Server error occurred while fetching the device list.",
@ -96,7 +94,7 @@ public interface DeviceManagementService {
Response getDevices( Response getDevices(
@ApiParam( @ApiParam(
name = "name", name = "name",
value = "The device name, such as shamu, bullhead or angler.", value = "The device name, such as shamu, bullhead or angler Nexus device names. ",
required = false) required = false)
@Size(max = 45) @Size(max = 45)
String name, String name,
@ -109,47 +107,55 @@ public interface DeviceManagementService {
String type, String type,
@ApiParam( @ApiParam(
name = "user", name = "user",
value = "Username of owner of the devices.", value = "The username of the owner of the device.",
required = false) required = false)
@QueryParam("user") @QueryParam("user")
String user, String user,
@ApiParam( @ApiParam(
name = "ownership", name = "ownership",
allowableValues = "BYOD, COPE", allowableValues = "BYOD, COPE",
value = "Ownership of the devices to be fetched registered under.", value = "Provide the ownership status of the device. The following values can be assigned:\n" +
"- BYOD: Bring Your Own Device\n" +
"- COPE: Corporate-Owned, Personally-Enabled",
required = false) required = false)
@QueryParam("ownership") @QueryParam("ownership")
@Size(max = 45) @Size(max = 45)
String ownership, String ownership,
@ApiParam( @ApiParam(
name = "status", name = "status",
value = "Enrollment status of devices to be fetched.", value = "Provide the device status details, such as active or inactive.",
required = false) required = false)
@QueryParam("status") @QueryParam("status")
@Size(max = 45) @Size(max = 45)
String status, String status,
@ApiParam( @ApiParam(
name = "since", name = "since",
value = "Last modified timestamp", value = "Checks if the requested variant was created since the specified date-time.\n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@QueryParam("since") @QueryParam("since")
String since, String since,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Timestamp of the last modified date", value = "Checks if the requested variant was modified, since the specified date-time.\n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String timestamp, String timestamp,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many device details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") @QueryParam("limit")
int limit); int limit);
@ -159,14 +165,14 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get information of the requested device.", value = "Getting Details of a Device",
notes = "Returns information of the requested device.", notes = "Get the details of a device by specifying the device type and device identifier.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Successfully fetched information of the device.", message = "OK. \n Successfully fetched the details of the device.",
response = Device.class, response = Device.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -178,25 +184,24 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. Empty body because the client already has the latest " + message = "Not Modified. Empty body because the client already has the latest version of the requested resource.\n"),
"version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n No device is found under the provided type and id.", message = "Not Found. \n A device with the specified device type and id was not found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while retrieving information requested device.", "Server error occurred while retrieving the device details.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view")
@ -204,20 +209,23 @@ public interface DeviceManagementService {
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", value = "The device type, such as ios, android or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "The device identifier of the device.", value = "The device identifier of the device you want ot get details.",
required = true) required = true)
@PathParam("id") @PathParam("id")
@Size(max = 45) @Size(max = 45)
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);
@ -228,8 +236,8 @@ public interface DeviceManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get Feature Details of a Device", value = "Getting Feature Details of a Device",
notes = "WSO2 EMM features enable you to carry out many operations on a given device platform. " + notes = "WSO2 EMM features enable you to carry out many operations based on the device platform. " +
"Using this REST API you can get the features that can be carried out on a preferred device type," + "Using this REST API you can get the features that can be carried out on a preferred device type," +
" such as iOS, Android or Windows.", " such as iOS, Android or Windows.",
tags = "Device Management") tags = "Device Management")
@ -237,7 +245,7 @@ public interface DeviceManagementService {
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n List of features of the device is returned", message = "OK. \n Successfully fetched the list of features.",
response = Feature.class, response = Feature.class,
responseContainer = "List", responseContainer = "List",
responseHeaders = { responseHeaders = {
@ -250,12 +258,12 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 303, code = 303,
message = "See Other. \n " + message = "See Other. \n " +
"Source can be retrieved from the URL specified at the Location header.", "The source can be retrieved from the URL specified in the location header.",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -270,7 +278,7 @@ public interface DeviceManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Device of which the feature list is requested, is not found.", message = "Not Found. \n The specified device can not be found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -278,7 +286,7 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while retrieving feature list of the device.", "Server error occurred while retrieving the feature list for the device platform.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view")
@ -286,20 +294,24 @@ public interface DeviceManagementService {
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", value = "The device type, such as ios, android or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "The device identifier of the device.", value = "The device identifier of the device.\n" +
"INFO: Make sure to add the ID of a device that is already registered with WSO2 EMM.",
required = true) required = true)
@PathParam("id") @PathParam("id")
@Size(max = 45) @Size(max = 45)
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);
@ -310,15 +322,14 @@ public interface DeviceManagementService {
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Advanced search for devices.", value = "Advanced Search for Devices",
notes = "Carry out an advanced search of devices.", notes = "Search for devices by filtering the search result through the specified search terms.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Device list searched for has successfully been retrieved. Location header " + message = "OK. \n Successfully retrieved the device information.",
"contains URL of newly enrolled device",
response = DeviceList.class, response = DeviceList.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -330,50 +341,51 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified. \n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n " + message = "Not Modified. \n " +
"Empty body because the client already has the latest version of the requested resource."), "Empty body because the client already has the latest version of the requested resource.\n"),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Acceptable.\n TIt is likely that no device is found upon the " + message = "Not Acceptable.\n The existing device did not match the values specified in the device search.",
"provided filters",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format."), message = "Unsupported media type. \n The format of the requested entity was not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while enrolling the device.", "Server error occurred while getting the device details.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view")
Response searchDevices( Response searchDevices(
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many activity details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") @QueryParam("limit")
int limit, int limit,
@ApiParam( @ApiParam(
name = "searchContext", name = "searchContext",
value = "List of device properties as search conditions.", value = "The properties to advanced search devices.",
required = true) required = true)
SearchContext searchContext); SearchContext searchContext);
@ -382,14 +394,14 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Getting installed application details of a device.", value = "Getting Installed Application Details of a Device",
notes = "Get the list of applications that a device has subscribed.", notes = "Get the list of applications subscribed to by a device.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n List of applications installed into the device is returned", message = "OK. \n Successfully fetched the list of applications.",
response = Application.class, response = Application.class,
responseContainer = "List", responseContainer = "List",
responseHeaders = { responseHeaders = {
@ -402,13 +414,12 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the " description = "Date and time the resource was last modified\n" +
+ "last time.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 303, code = 303,
message = "See Other. \n " + message = "See Other. \n " +
"Source can be retrieved from the URL specified at the Location header.", "The source can be retrieved from the URL specified in the location header.\n",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -416,16 +427,14 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n " + message = "Not Modified. \n " +
"Empty body because the client already has the latest version of the " "Empty body because the client already has the latest version of the requested resource."),
+ "requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Device of which the application list is requested, is " message = "Not Found. \n The specified device does not exist.",
+ "not found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -433,14 +442,16 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while retrieving installed application list of the device.", "Server error occurred while retrieving the list of installed application on the device.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view")
Response getInstalledApplications( Response getInstalledApplications(
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", required = true) value = "The device type, such as ios, android or windows.",
required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ -453,20 +464,24 @@ public interface DeviceManagementService {
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince, String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many application details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") @QueryParam("limit")
int limit); int limit);
@ -476,16 +491,14 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Getting paginated details for operations on a device.", value = "Getting Device Operation Details",
notes = "You will carry out many operations on a device. In a situation where you wish to view " notes = "Get the details of operations carried out on a selected device.",
+ "the all the operations carried out on a device it is not feasible to show all the "
+ "details on one page therefore the details are paginated.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n List of operations scheduled for the device is returned", message = "OK. \n Successfully fetched the list of operations scheduled for the device.",
response = Operation.class, response = Operation.class,
responseContainer = "List", responseContainer = "List",
responseHeaders = { responseHeaders = {
@ -498,13 +511,12 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the " description = "Date and time the resource was last modified" +
+ "last time.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 303, code = 303,
message = "See Other. \n " + message = "See Other. \n " +
"Source can be retrieved from the URL specified at the Location header.", "The source can be retrieved from the URL specified in the location header.\n",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -512,16 +524,14 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n " + message = "Not Modified. \n " +
"Empty body because the client already has the latest version of the " "Empty body because the client already has the latest version of the requested resource."),
+ "requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Device of which the operation list is requested, is not " message = "Not Found. \n The specified device does not exist.",
+ "found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -529,7 +539,7 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while retrieving operation list scheduled for the device.", "Server error occurred while retrieving the operation list scheduled for the device.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view") @Permission(name = "View Devices", permission = "/device-mgt/devices/owning-device/view")
@ -537,34 +547,39 @@ public interface DeviceManagementService {
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", value = "The device type, such as ios, android or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "The device identifier of the device.", value = "The device identifier of the device you wish to get details.\n" +
"INFO: Make sure to add the ID of a device that is already registered with WSO2 EMM.",
required = true) required = true)
@PathParam("id") @PathParam("id")
@Size(max = 45) @Size(max = 45)
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time " value = "Checks if the requested variant was modified, since the specified date-time. \n" +
+ "specified", "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince, String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many activity details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") @QueryParam("limit")
int limit); int limit);
@ -573,17 +588,16 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the effective policy calculated for a device.", value = "Get the details of the policy that is enforced on a device.",
notes = "When a device registers with WSO2 EMM a policy is enforced on the device. Initially the " notes = "A policy is enforced on all the devices that registers with WSO2 EMM." +
+ "EMM filters the policies based on the Platform (device type), filters based on the " "WSO2 EMM filters the policies based on the device platform (device type)," +
+ "device ownership type , filters based on the user role or name and finally the policy" "the device ownership type, the user role or name and finally, the policy that matches these filters will be enforced on the device.",
+ " is enforced on the device.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Effective policy calculated for the device is returned", message = "OK. \n Successfully returned the details of the policy enforced on the device.",
response = Policy.class, response = Policy.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -595,13 +609,12 @@ public interface DeviceManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the " description = "Date and time the resource was last modified.\n" +
+ "last time.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 303, code = 303,
message = "See Other. \n " + message = "See Other. \n " +
"Source can be retrieved from the URL specified at the Location header.", "The source can be retrieved from the URL specified in the location header.\n",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -609,16 +622,14 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n " + message = "Not Modified. \n " +
"Empty body because the client already has the latest version of the " "Empty body because the client already has the latest version of the requested resource."),
+ "requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Device of which the effective policy is requested, is " message = "Not Found. \n The specified device does not exist.",
+ "not found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -626,7 +637,7 @@ public interface DeviceManagementService {
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while retrieving the effective policy calculated for the device.", "Server error occurred while retrieving the policy details that is enforced on the device.",
response = ErrorResponse.class) response = ErrorResponse.class)
} }
) )
@ -635,21 +646,23 @@ public interface DeviceManagementService {
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", value = "The device type, such as ios, android or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "Device Identifier", value = "The device identifier.",
required = true) required = true)
@PathParam("id") @PathParam("id")
@Size(max = 45) @Size(max = 45)
String id, String id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time " value = "Checks if the requested variant was modified, since the specified date-time. \n" +
+ "specified", "Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);
@ -660,11 +673,9 @@ public interface DeviceManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the effective policy calculated for a device.", value = "Getting Policy Compliance Details of a Device",
notes = "When a device registers with WSO2 EMM a policy is enforced on the device. Initially the " notes = "A policy is enforced on the devices that register with WSO2 EMM. " +
+ "EMM filters the policies based on the Platform (device type), filters based on the " "The server checks if the settings in the device comply with the policy that is enforced on the device using this REST API.",
+ "device ownership type , filters based on the user role or name and finally the policy"
+ " is enforced on the device.",
tags = "Device Management") tags = "Device Management")
@ApiResponses( @ApiResponses(
value = { value = {

32
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/DeviceTypeManagementService.java
Unescape View File

@ -53,8 +53,8 @@ public interface DeviceTypeManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the list of device types registered.", value = "Getting the Supported Device Platforms",
notes = "Retrieves the list of device types of which the devices intended to be managed.", notes = "Get the list of device platforms supported by WSO2 EMM.",
tags = "Device Type Management") tags = "Device Type Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ -73,16 +73,14 @@ public interface DeviceTypeManagementService {
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = description =
"Date and time the resource has been modified the last time.\n" + "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
} }
), ),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = message =
"Not Modified. \n Empty body because the client has already the latest version of" + "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
" " +
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ -97,7 +95,9 @@ public interface DeviceTypeManagementService {
Response getDeviceTypes( Response getDeviceTypes(
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time.\n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);
@ -106,8 +106,9 @@ public interface DeviceTypeManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the list of features for a give device type.", value = "Get Feature Details of a Device Type",
notes = "Retrieves the list of features of a given device type.", notes = "The features in WSO2 EMM enables you to carry out many operations on a given device platform. " +
"Using this REST API you can get the features that can be carried out on a preferred device type, such as iOS, Android or Windows.",
tags = "Device Type Management") tags = "Device Type Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ -126,16 +127,14 @@ public interface DeviceTypeManagementService {
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = description =
"Date and time the resource has been modified the last time.\n" + "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
} }
), ),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = message =
"Not Modified. \n Empty body because the client has already the latest version of" + "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
" " +
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ -151,13 +150,16 @@ public interface DeviceTypeManagementService {
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "The device type, such as ios, android or windows.", value = "The device type, such as ios, android or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@PathParam("type") @PathParam("type")
@Size(max = 45) @Size(max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time.\n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);

35
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/NotificationManagementService.java
Unescape View File

@ -47,9 +47,8 @@ public interface NotificationManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Getting all device notification details.", value = "Getting All Device Notification Details",
notes = "Get the details of all notifications that were pushed to the device in WSO2 EMM using " notes = "Get the details of all the notifications that were pushed to the devices registered with WSO2 EMM using this REST API.",
+ "this REST API",
tags = "Device Notification Management") tags = "Device Notification Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ -67,20 +66,20 @@ public interface NotificationManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid notification status type " + message = "Bad Request. \n Invalid notification status type received. \n" +
"received. Valid status types are NEW | CHECKED", "Valid status types are NEW | CHECKED",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n No notification is available to be retrieved.", message = "Not Found. \n There are no notification.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -95,26 +94,30 @@ public interface NotificationManagementService {
Response getNotifications( Response getNotifications(
@ApiParam( @ApiParam(
name = "status", name = "status",
value = "Status of the notification.", value = "The status of the notification. Provide any of the following values: \n" +
" - NEW: Will keep the message in the unread state.\n" +
" - CHECKED: Will keep the message in the read state.",
allowableValues = "NEW, CHECKED", allowableValues = "NEW, CHECKED",
required = false) required = false)
@QueryParam("status") @Size(max = 45) @QueryParam("status") @Size(max = 45)
String status, String status,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince, String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false)
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many notification details you require from the starting pagination index/offset.",
required = false) required = false)
@QueryParam("limit") @QueryParam("limit")
int limit); int limit);
@ -137,7 +140,8 @@ public interface NotificationManagementService {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "Notification updated successfully. But the retrial of the updated " message = "Notification updated successfully. But the retrial of the updated "
+ "notification failed."), + "notification failed.",
response = Notification.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Error occurred while updating notification status.") message = "Error occurred while updating notification status.")
@ -147,8 +151,9 @@ public interface NotificationManagementService {
Response updateNotificationStatus( Response updateNotificationStatus(
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "Notification ID.", value = "The notification ID.",
required = true) required = true,
defaultValue = "1")
@PathParam("id") @Max(45) @PathParam("id") @Max(45)
int id); int id);
} }

156
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/PolicyManagementService.java
Unescape View File

@ -40,8 +40,7 @@ import java.util.List;
@API(name = "Device Policy Management", version = "1.0.0", context = "/api/device-mgt/v1.0/policies", @API(name = "Device Policy Management", version = "1.0.0", context = "/api/device-mgt/v1.0/policies",
tags = {"devicemgt_admin"}) tags = {"devicemgt_admin"})
@Api(value = "Device Policy Management", description = "This API carries all the necessary functionalities " + @Api(value = "Device Policy Management", description = "This API includes the functionality around device policy management")
"around device policy management")
@Path("/policies") @Path("/policies")
@Produces(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON)
@ -52,14 +51,15 @@ public interface PolicyManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Add a new policy.", value = "Adding a Policy",
notes = "This particular resource can be used to add a new policy, which will be created in in-active state.", notes = "Add a policy using this REST API command. When adding a policy you will have the option of saving the policy or saving and publishing the policy." +
"Using this REST API you are able to save a created Policy and this policy will be in the inactive state.",
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 201, code = 201,
message = "Created. \n Policy has successfully been created", message = "Created. \n Successfully created the policy.",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -73,13 +73,13 @@ public interface PolicyManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests.") "Used by caches, or in conditional requests.")
} }
), ),
@ApiResponse( @ApiResponse(
code = 303, code = 303,
message = "See Other. \n Source can be retrieved from the URL specified at the Location header.", message = "See Other. \n he source can be retrieved from the URL specified in the location header",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -90,11 +90,11 @@ public interface PolicyManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 401, code = 401,
message = "Not Found. \n Current logged in user is not authorized to add policies.", message = "Not Found. \n The user that is currently logged in is not authorized to add policies.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format."), message = "Unsupported media type. \n The format of the requested entity was not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
@ -105,17 +105,18 @@ public interface PolicyManagementService {
Response addPolicy( Response addPolicy(
@ApiParam( @ApiParam(
name = "policy", name = "policy",
value = "Policy details related to the operation.", value = "The properties required to add a new policy.",
required = true) required = true,
defaultValue = "{\"policyName\":\"test\",\"description\":\"test desc\",\"compliance\":\"ENFORCE\",\"ownershipType\":\"string\",\"active\":false,\"profile\":{\"profileId\":0,\"profileName\":\"string\",\"tenantId\":0,\"deviceType\":\"string\",\"createdDate\":\"2016-10-07T04:50:01.931Z\",\"updatedDate\":\"2016-10-07T04:50:01.931Z\",\"profileFeaturesList\":[{\"id\":0,\"featureCode\":\"string\",\"profileId\":0,\"deviceType\":\"string\",\"content\":{}}]},\"roles\":[\"string\"],\"deviceIdentifiers\":[{\"id\":\"string\",\"type\":\"string\"}],\"users\":[\"string\"]}")
@Valid PolicyWrapper policy); @Valid PolicyWrapper policy);
@GET @GET
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get details of policies.", value = "Getting Details of Policies",
responseContainer = "List", responseContainer = "List",
notes = "Retrieve the details of all the policies that have been created in EMM.", notes = "Retrieve the details of all the policies in WSO2 EMM.",
response = Policy.class, response = Policy.class,
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
@ -135,13 +136,13 @@ public interface PolicyManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
} }
), ),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
@ -151,28 +152,31 @@ public interface PolicyManagementService {
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = ("Internal Server Error. \n Server error occurred while fetching " + message = ("Internal Server Error. \n Server error occurred while fetching the policies."),
"policies."),
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View policies", permission = "/device-mgt/policies/view") @Permission(name = "View policies", permission = "/device-mgt/policies/view")
Response getPolicies( Response getPolicies(
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince, String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") @QueryParam("offset")
int offset, int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Maximum size of resource array to return.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") @QueryParam("limit")
int limit); int limit);
@ -181,8 +185,8 @@ public interface PolicyManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get details of a policy.", value = "Getting Details of a Policy",
notes = "Retrieve the details of a given policy that has been created in EMM.", notes = "Retrieve the details of a policy that is in WSO2 EMM.",
response = Policy.class, response = Policy.class,
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
@ -201,20 +205,20 @@ public interface PolicyManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
} }
), ),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n No policy is found with the given id.", message = "Not Found. \n A specified policy was not found.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the " + message = "Internal Server Error. \n Server error occurred while fetching the " +
@ -225,13 +229,16 @@ public interface PolicyManagementService {
Response getPolicy( Response getPolicy(
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "Policy identifier", value = "The policy identifier.",
required = true) required = true,
defaultValue = "")
@PathParam("id") @PathParam("id")
int id, int id,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") @HeaderParam("If-Modified-Since")
String ifModifiedSince); String ifModifiedSince);
@ -242,15 +249,14 @@ public interface PolicyManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "PUT",
value = "Update a policy.", value = "Updating a Policy",
notes = "If you wish to make changes to an existing policy, that can be done by updating the policy using " + notes = "Make changes to an existing policy by updating the policy using this resource.",
"this resource.",
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Policy has been updated successfully", message = "OK. \n Successfully updated the policy.",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -264,7 +270,7 @@ public interface PolicyManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests.") "Used by caches, or in conditional requests.")
} }
), ),
@ -274,11 +280,11 @@ public interface PolicyManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format."), message = "Unsupported media type. \n The format of the requested entity was not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
@ -289,13 +295,14 @@ public interface PolicyManagementService {
Response updatePolicy( Response updatePolicy(
@ApiParam( @ApiParam(
name = "id", name = "id",
value = "The device identifier of the device.", value = "The policy ID.",
required = true) required = true,
defaultValue = "1")
@PathParam("id") @PathParam("id")
int id, int id,
@ApiParam( @ApiParam(
name = "policy", name = "policy",
value = "Policy details related to the operation.", value = "Update the required property details.",
required = true) required = true)
@Valid PolicyWrapper policy); @Valid PolicyWrapper policy);
@ -305,38 +312,39 @@ public interface PolicyManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Remove multiple policies.", value = "Removing Multiple Policies",
notes = "In situations where you need to delete more than one policy you can do so using this API.", notes = "Delete one or more than one policy using this API.",
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Policies have successfully been removed"), message = "OK. \n Successfully removed the policy."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not " message = "Unsupported media type. \n The format of the requested entity was not supported.\n "
+ "supported format."), + "supported format."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while bulk removing policies.", "Server error occurred whilst bulk removing policies.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage")
Response removePolicies( Response removePolicies(
@ApiParam( @ApiParam(
name = "policyIds", name = "policyIds",
value = "Policy id list to be deleted.", value = "The list of policy IDs to be removed.",
required = true) required = true,
defaultValue = "[1]")
List<Integer> policyIds); List<Integer> policyIds);
@POST @POST
@ -344,35 +352,35 @@ public interface PolicyManagementService {
@ApiOperation( @ApiOperation(
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "POST",
value = "Activating policies.", value = "Activating Policies",
notes = "Using the REST API command you are able to publish a policy in order to bring a policy that is " + notes = "Publish a policy using this API to bring a policy that is in the inactive state to the active state.",
"in the inactive state to the active state.",
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "Policies have been successfully activated."), message = "Successfully activated the policy."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource does not exist.", message = "Not Found. \n The specified resource/s does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "ErrorResponse in activating policies.", message = "Sever error whilst activating the policies.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage")
Response activatePolicies( Response activatePolicies(
@ApiParam( @ApiParam(
name = "policyIds", name = "policyIds",
value = "Policy ID list to be activated.", value = "The list of the policy IDs to be activated",
required = true) required = true,
defaultValue = "[1]")
List<Integer> policyIds); List<Integer> policyIds);
@POST @POST
@ -380,23 +388,22 @@ public interface PolicyManagementService {
@ApiOperation( @ApiOperation(
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "POST",
value = "Deactivating policies.", value = "Deactivating Policies",
notes = "Using the REST API command you are able to unpublish a policy in order to bring a " notes = "Unpublish a policy using this API to bring a policy that is in the active state to the inactive state.",
+ "policy that is in the active state to the inactive state.",
tags = "Device Policy Management") tags = "Device Policy Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "Policies have been successfully deactivated."), message = "Successfully deactivated the policy."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
@ -407,8 +414,9 @@ public interface PolicyManagementService {
Response deactivatePolicies( Response deactivatePolicies(
@ApiParam( @ApiParam(
name = "policyIds", name = "policyIds",
value = "Policy ID list to be deactivated.", value = "The list of Policy IDs that needs to be deactivated.",
required = true) required = true,
defaultValue = "[1]")
List<Integer> policyIds); List<Integer> policyIds);
@PUT @PUT
@ -418,7 +426,7 @@ public interface PolicyManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "PUT",
value = "Applying Changes on Policies.", value = "Applying Changes on Policies",
notes = "Policies in the active state will be applied to new device that register with WSO2 EMM based on" + notes = "Policies in the active state will be applied to new device that register with WSO2 EMM based on" +
" the policy enforcement criteria . In a situation where you need to make changes to existing" + " the policy enforcement criteria . In a situation where you need to make changes to existing" +
" policies (removing, activating, deactivating and updating) or add new policies, the existing" + " policies (removing, activating, deactivating and updating) or add new policies, the existing" +
@ -430,7 +438,7 @@ public interface PolicyManagementService {
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "Changes have been successfully updated."), message = "Successfully updated the EMM server with the policy changes."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "ErrorResponse in deactivating policies.", message = "ErrorResponse in deactivating policies.",
@ -446,23 +454,22 @@ public interface PolicyManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "PUT",
value = "Prioritizing policies.", value = "Updating the Policy Priorities",
notes = "If you wish to make changes to the existing policy priority order, you can do so by " notes = "Make changes to the existing policy priority order by updating the priority order using this API.",
+ "updating the priority order using this end-point",
tags = "Device Policy Management" tags = "Device Policy Management"
) )
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "Policy Priorities successfully updated."), message = "Successfully updated the policy priority order."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Policy priorities did not update. Bad Request.", message = "Bad Request. Did not update the policy priority order.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Exception in updating policy priorities.", message = "Exception in updating the policy priorities.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "Manage policies", permission = "/device-mgt/policies/manage") @Permission(name = "Manage policies", permission = "/device-mgt/policies/manage")
@ -470,7 +477,8 @@ public interface PolicyManagementService {
@ApiParam( @ApiParam(
name = "priorityUpdatedPolicies", name = "priorityUpdatedPolicies",
value = "List of policies with priorities", value = "List of policies with priorities",
required = true) required = true,
defaultValue = "[{id:1,priority:2}]")
List<PriorityUpdatedPolicyWrapper> priorityUpdatedPolicies); List<PriorityUpdatedPolicyWrapper> priorityUpdatedPolicies);

23
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/RoleManagementService.java
Unescape View File

@ -99,13 +99,13 @@ public interface RoleManagementService {
@HeaderParam("If-Modified-Since") String ifModifiedSince, @HeaderParam("If-Modified-Since") String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "The starting pagination index for the complete list qualified items.", value = "The starting pagination index for the complete list of qualified items.",
required = false, required = false,
defaultValue = "0") defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Provide how many roles details you require from the starting pagination index/offset.", value = "Provide how many role details you require from the starting pagination index/offset.",
required = false, required = false,
defaultValue = "5") defaultValue = "5")
@QueryParam("limit") int limit); @QueryParam("limit") int limit);
@ -348,11 +348,13 @@ public interface RoleManagementService {
name = "roleName", name = "roleName",
value = "The name of the role.", value = "The name of the role.",
required = true, required = true,
defaultValue = "engineer") defaultValue = "admin")
@PathParam("roleName") String roleName, @PathParam("roleName") String roleName,
@ApiParam( @ApiParam(
name = "role", name = "role",
value = "The properties required to update a role.", value = "The properties required to update a role.\n" +
"NOTE: Don't change the role and the permissions of the admin user. " +
"If you want to try out this API by updating all the properties, create a new role and update the properties accordingly.",
required = true) RoleInfo role); required = true) RoleInfo role);
@DELETE @DELETE
@ -384,9 +386,9 @@ public interface RoleManagementService {
Response deleteRole( Response deleteRole(
@ApiParam( @ApiParam(
name = "roleName", name = "roleName",
value = "The name of the role that needs to de deleted.", value = "The name of the role that needs to de deleted.\n" +
required = true, "NOTE: Don't delete the admin role",
defaultValue = "engineer") required = true)
@PathParam("roleName") String roleName); @PathParam("roleName") String roleName);
@PUT @PUT
@ -443,15 +445,16 @@ public interface RoleManagementService {
Response updateUsersOfRole( Response updateUsersOfRole(
@ApiParam( @ApiParam(
name = "roleName", name = "roleName",
value = "Name of the role.", value = "The name of the role.",
required = true) required = true,
defaultValue = "admin")
@PathParam("roleName") String roleName, @PathParam("roleName") String roleName,
@ApiParam( @ApiParam(
name = "users", name = "users",
value = "Define the users that belong to the role.\n" + value = "Define the users that belong to the role.\n" +
"Multiple users can be added to a role by using comma separated values. ", "Multiple users can be added to a role by using comma separated values. ",
required = true, required = true,
defaultValue = "[jim]" defaultValue = "[admin]"
) List<String> users); ) List<String> users);
} }

194
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/UserManagementService.java
Unescape View File

@ -42,14 +42,14 @@ public interface UserManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Add a user.", value = "Adding a User",
notes = "A new user can be added to the user management system via this resource", notes = "WSO2 EMM supports user management. Add a new user to the WSO2 EMM user management system via this REST API",
tags = "User Management") tags = "User Management")
@ApiResponses( @ApiResponses(
value = { value = {
@ApiResponse( @ApiResponse(
code = 201, code = 201,
message = "Created. \n User has successfully been created", message = "Created. \n Successfully created the user.",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Location", name = "Content-Location",
@ -63,7 +63,7 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
@ -87,7 +87,8 @@ public interface UserManagementService {
Response addUser( Response addUser(
@ApiParam( @ApiParam(
name = "user", name = "user",
value = "Information of the user to be added", value = "Provide the property details to add a new user.\n" +
"Double click the example value and click try out. ",
required = true) UserInfo user); required = true) UserInfo user);
@GET @GET
@ -95,15 +96,14 @@ public interface UserManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Getting details of a user.", value = "Getting Details of a User",
notes = "If you wish to get the details of a specific user that is registered with EMM," notes = "Get the details of a user registered with WSO2 EMM using the REST API.",
+ " you can do so using the REST API.",
response = BasicUserInfo.class, response = BasicUserInfo.class,
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Successfully fetched the requested role.", message = "OK. \n Successfully fetched the details of the specified user.",
response = BasicUserInfo.class, response = BasicUserInfo.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -115,15 +115,15 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -132,24 +132,27 @@ public interface UserManagementService {
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server ErrorResponse. \n Server error occurred while" + message = "Internal Server ErrorResponse. \n Server error occurred while" +
" fetching the requested user.", " fetching the ruser details.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Users", permission = "/device-mgt/users/view") @Permission(name = "View Users", permission = "/device-mgt/users/view")
Response getUser( Response getUser(
@ApiParam( @ApiParam(
name = "username", name = "username",
value = "Username of the user to be fetched.", value = "Provide the username of the user.",
required = true) required = true,
defaultValue = "admin")
@PathParam("username") String username, @PathParam("username") String username,
@ApiParam( @ApiParam(
name = "domain", name = "domain",
value = "Domain name of the user store.", value = "The domain name of the user store.",
required = false) required = false)
@QueryParam("domain") String domain, @QueryParam("domain") String domain,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time.\n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String ifModifiedSince); @HeaderParam("If-Modified-Since") String ifModifiedSince);
@ -159,14 +162,14 @@ public interface UserManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "PUT",
value = "Update details of a user", value = "Updating Details of a User",
notes = "There will be situations where you will want to update the user details. In such " notes = "There will be situations where you will want to update the user details. In such "
+ "situation you can update the user details using this REST API.", + "situation you can update the user details using this REST API.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n User has been updated successfully", message = "OK. \n Successfully updated the details of the specified user.",
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
name = "Content-Type", name = "Content-Type",
@ -177,7 +180,7 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests.")}), "Used by caches, or in conditional requests.")}),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
@ -185,11 +188,11 @@ public interface UserManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format.", message = "Unsupported media type. \n The format of the requested entity was not supported.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
@ -201,34 +204,35 @@ public interface UserManagementService {
Response updateUser( Response updateUser(
@ApiParam( @ApiParam(
name = "username", name = "username",
value = "Username of the user to be updated.", value = "The username of the user.",
required = true) required = true,
defaultValue = "admin")
@PathParam("username") String username, @PathParam("username") String username,
@ApiParam( @ApiParam(
name = "domain", name = "domain",
value = "Domain name of the user store.", value = "The domain name of the user store.",
required = false) required = false)
@QueryParam("domain") String domain, @QueryParam("domain") String domain,
@ApiParam( @ApiParam(
name = "userData", name = "userData",
value = "User related details.", value = "Update the user details.\n" +
"NOTE: Do not change the admin username, password and roles when trying out this API.",
required = true) UserInfo userData); required = true) UserInfo userData);
@DELETE @DELETE
@Path("/{username}") @Path("/{username}")
@ApiOperation( @ApiOperation(
httpMethod = "DELETE", httpMethod = "DELETE",
value = "Deleting a user.", value = "Deleting a User",
notes = "In a situation where an employee leaves the organization you will need to remove the" notes = "When an employee leaves the organization, you can remove the user details from WSO2 EMM using this REST API.",
+ " user details from EMM. In such situations you can use this REST API to remove a user.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n User has successfully been removed"), message = "OK. \n Successfully removed the user from WSO2 EMM."),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
@ -239,11 +243,16 @@ public interface UserManagementService {
}) })
@Permission(name = "Manage Users", permission = "/device-mgt/users/manage") @Permission(name = "Manage Users", permission = "/device-mgt/users/manage")
Response removeUser( Response removeUser(
@ApiParam(name = "username", value = "Username of the user to be deleted.", required = true) @ApiParam(
name = "username",
value = "Username of the user to be deleted.\n" +
"INFO: If you want to try out this API, make sure to create a new user and then remove that user. Do not remove the admin user.",
required = true,
defaultValue = "[Create a new user named Jim, and then try out this API.]")
@PathParam("username") String username, @PathParam("username") String username,
@ApiParam( @ApiParam(
name = "domain", name = "domain",
value = "Domain name of the user store.", value = "The domain name of the user store.",
required = false) required = false)
@QueryParam("domain") String domain); @QueryParam("domain") String domain);
@ -252,14 +261,13 @@ public interface UserManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get the role list of a user.", value = "Getting the Role Details of a User",
notes = "A user can be assigned to one or more role in EMM. Using this REST API you are " notes = "A user can be assigned to one or more role in EMM. Using this REST API you can get the role/roles a user is assigned to.",
+ "able to get the role/roles a user is assigned to.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Successfully fetched the role list assigned to the user.", message = "OK. \n Successfully fetched the list of roles the specified user is assigned to.",
response = RoleList.class, response = RoleList.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -271,15 +279,15 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.\n",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -287,17 +295,21 @@ public interface UserManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the role list" + message = "Internal Server Error. \n Server error occurred while fetching the list of roles" +
" assigned to the user.", " assigned to the specified user.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Users", permission = "/device-mgt/users/view") @Permission(name = "View Users", permission = "/device-mgt/users/view")
Response getRolesOfUser( Response getRolesOfUser(
@ApiParam(name = "username", value = "Username of the user.", required = true) @ApiParam(
name = "username",
value = "The username of the user.",
required = true,
defaultValue = "admin")
@PathParam("username") String username, @PathParam("username") String username,
@ApiParam( @ApiParam(
name = "domain", name = "domain",
value = "Domain name of the user store.", value = "The domain name of the user store.",
required = false) required = false)
@QueryParam("domain") String domain); @QueryParam("domain") String domain);
@ -305,14 +317,14 @@ public interface UserManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get user list", value = "Getting Details of Users",
notes = "If you wish to get the details of all the users registered with EMM, you can do so " notes = "You are able to manage users in WSO2 EMM by adding, updating and removing users. If you wish to get the list of users registered with WSO2 EMM, you can do so "
+ "using this REST API", + "using this REST API",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Successfully fetched the requested users.", message = "OK. \n Successfully fetched the list of users registered with WSO2 EMM.",
response = BasicUserInfoList.class, response = BasicUserInfoList.class,
responseHeaders = { responseHeaders = {
@ResponseHeader( @ResponseHeader(
@ -324,42 +336,46 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported", message = "Not Acceptable.\n The requested media type is not supported",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the user list.", message = "Internal Server Error. \n Server error occurred while fetching the list of WSO2 EMM users.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Users", permission = "/device-mgt/users/view") @Permission(name = "View Users", permission = "/device-mgt/users/view")
Response getUsers( Response getUsers(
@ApiParam( @ApiParam(
name = "filter", name = "filter",
value = "Username of the user details to be fetched.", value = "The username of the user.",
required = false) required = false)
@QueryParam("filter") String filter, @QueryParam("filter") String filter,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Timestamp of the last modified date", value = "Checks if the requested variant was modified, since the specified date-time\n." +
"Provide the value in the Java Date Format: EEE, d MMM yyyy HH:mm:ss Z.\n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String timestamp, @HeaderParam("If-Modified-Since") String timestamp,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many user details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") int limit); @QueryParam("limit") int limit);
@GET @GET
@ -367,8 +383,8 @@ public interface UserManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get user count", value = "Getting the User Count",
notes = "If you wish to get the user count registered with EMM, you can do so using this REST API", notes = "Get the number of users in WSO2 EMM via this REST API.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
@ -386,7 +402,7 @@ public interface UserManagementService {
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the user list.", message = "Internal Server Error. \n Server error occurred while fetching the total number of users in WSO2 EMM.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Users", permission = "/device-mgt/users/view") @Permission(name = "View Users", permission = "/device-mgt/users/view")
@ -397,17 +413,16 @@ public interface UserManagementService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Search for a username.", value = "Searching for a User Name",
notes = "If you are unsure of the " notes = "If you are unsure of the user name of a user and need to retrieve the details of a specific user, you can "
+ "user name of a user and need to retrieve the details of a specific user, you can "
+ "search for that user by giving a character or a few characters in the username. " + "search for that user by giving a character or a few characters in the username. "
+ "You will be given a list of users having the user name with the exact order of the " + "You will be given a list of users having the user name in the exact order of the "
+ "characters you provided.", + "characters you provided.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Successfully fetched the username list that matches the given filter.", message = "OK. \n Successfully fetched the list of users that matched the given filter.",
response = String.class, response = String.class,
responseContainer = "List", responseContainer = "List",
responseHeaders = { responseHeaders = {
@ -420,43 +435,46 @@ public interface UserManagementService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the requested resource."), message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported", message = "Not Acceptable.\n The requested media type is not supported",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the username " + message = "Internal Server Error. \n Server error occurred while fetching the list of users that matched the given filter.",
"list that matches the given filter.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "View Users", permission = "/device-mgt/users/view") @Permission(name = "View Users", permission = "/device-mgt/users/view")
Response getUserNames( Response getUserNames(
@ApiParam( @ApiParam(
name = "filter", name = "filter",
value = "Username/part of the user name to search.", value = "Provide a character or a few character in the user name",
required = true) required = true)
@QueryParam("filter") String filter, @QueryParam("filter") String filter,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Timestamp of the last modified date", value = "Checks if the requested variant was modified, since the specified date-time\n." +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z\n. " +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String timestamp, @HeaderParam("If-Modified-Since") String timestamp,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many user details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") int limit); @QueryParam("limit") int limit);
@PUT @PUT
@ -465,36 +483,37 @@ public interface UserManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "PUT", httpMethod = "PUT",
value = "Changing the user password.", value = "Changing the User Password",
notes = "A user is able to change the password to secure their EMM profile via this REST API.", notes = "A user is able to change the password to secure their WSO2 EMM profile via this REST API.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Credentials of the user have been updated successfully"), message = "OK. \n Successfully updated the user credentials."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format.", message = "Unsupported media type. \n The format of the requested entity was not supported.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while updating credentials of the user.", "Server error occurred while updating the user credentials.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "Reset user password", permission = "/login") @Permission(name = "Reset user password", permission = "/login")
Response resetPassword( Response resetPassword(
@ApiParam( @ApiParam(
name = "credentials", name = "credentials",
value = "Credential.", value = "The property to change the password.\n" +
"The password should be within 5 to 30 characters",
required = true) OldPasswordResetWrapper credentials); required = true) OldPasswordResetWrapper credentials);
@POST @POST
@ -503,29 +522,30 @@ public interface UserManagementService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Send invitation mail.", value = "Sending Enrollment Invitations to Users",
notes = "A user is able to send invitation mail via this REST API.", notes = "Send the users a mail inviting them to download the EMM mobile application on their devices using the REST API given below.\n" +
"Before running the REST API command to send the enrollment invitations to users make sure to configure WSO2 EMM as explained in step 4, under the WSO2 EMM general server configurations documentation.",
tags = "User Management") tags = "User Management")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Invitation mails have been sent."), message = "OK. \n Successfully sent the invitation mail."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist.", message = "Not Found. \n The specified resource does not exist.\n",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format.", message = "Unsupported media type. \n The format of the requested entity was not supported.\n",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
"Server error occurred while updating credentials of the user.", "Server error occurred while updating the user credentials.",
response = ErrorResponse.class) response = ErrorResponse.class)
}) })
@Permission(name = "Manage Users", permission = "/device-mgt/users/manage") @Permission(name = "Manage Users", permission = "/device-mgt/users/manage")

40
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/DeviceManagementAdminService.java
Unescape View File

@ -43,8 +43,8 @@ public interface DeviceManagementAdminService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get devices by name.", value = "Getting Details of a Device",
notes = "Get devices by name of the device and tenant that they belong to.", notes = "Get the details of a device by searching via the device name, device type and the tenant domain.",
response = Device.class, response = Device.class,
responseContainer = "List", responseContainer = "List",
tags = "Device Management Administrative Service") tags = "Device Management Administrative Service")
@ -62,20 +62,19 @@ public interface DeviceManagementAdminService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " + message = "Not Modified. Empty body because the client already has the latest version of the requested resource.\n"),
"the requested resource."),
@ApiResponse( @ApiResponse(
code = 401, code = 401,
message = "Unauthorized.\n The requested resource access is unauthorized", message = "Unauthorized.\n The unauthorized access to the requested resource.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found.\n No device found that matches the given name.", message = "Not Found.\n The specified device does not exist",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
@ -89,37 +88,44 @@ public interface DeviceManagementAdminService {
Response getDevicesByName( Response getDevicesByName(
@ApiParam( @ApiParam(
name = "name", name = "name",
value = "Name of the device.", value = "The name of the device.If you are unsure of the name of the device, run the GET /devices API that is under Device Management.",
required = true) required = true)
@QueryParam("name") @QueryParam("name")
@Size(max = 45) @Size(max = 45)
String name, String name,
@ApiParam( @ApiParam(
name = "type", name = "type",
value = "Type of the device.", value = "The type of the device, such as android, ios or windows.",
required = true) required = true,
allowableValues = "android, ios, windows")
@QueryParam("type") @QueryParam("type")
@Size(min = 2, max = 45) @Size(min = 2, max = 45)
String type, String type,
@ApiParam( @ApiParam(
name = "tenant-domain", name = "tenant-domain",
value = "Name of the tenant.", value = "The name of the tenant.\n" +
required = true) "The default tenant domain of WSO2 EMM is carbon.super",
required = true,
defaultValue = "carbon.super")
@QueryParam("tenant-domain") String tenantDomain, @QueryParam("tenant-domain") String tenantDomain,
@ApiParam( @ApiParam(
name = "If-Modified-Since", name = "If-Modified-Since",
value = "Validates if the requested variant has not been modified since the time specified", value = "Checks if the requested variant was modified, since the specified date-time. \n" +
"Provide the value in the following format: EEE, d MMM yyyy HH:mm:ss Z. \n" +
"Example: Mon, 05 Jan 2014 15:10:00 +0200",
required = false) required = false)
@HeaderParam("If-Modified-Since") String ifModifiedSince, @HeaderParam("If-Modified-Since") String ifModifiedSince,
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "The starting pagination index for the complete list of qualified items.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Provide how many activity details you require from the starting pagination index/offset.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") int limit); @QueryParam("limit") int limit);
} }

20
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/GroupManagementAdminService.java
Unescape View File

@ -51,8 +51,9 @@ public interface GroupManagementAdminService {
@ApiOperation( @ApiOperation(
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "GET", httpMethod = "GET",
value = "Get groups by the name.", value = "Grouping Devices",
notes = "Get devices the name of device and tenant.", notes = "Many devices can be registered with WSO2 IoTS. In order to manage them in an efficient manner, " +
"you can group devices and view the data gathered by the devices or share the groups with users so that they can monitor the devices in the respective group.",
response = DeviceGroupWrapper.class, response = DeviceGroupWrapper.class,
responseContainer = "List", responseContainer = "List",
tags = "Group Management Administrative Service") tags = "Group Management Administrative Service")
@ -70,25 +71,24 @@ public interface GroupManagementAdminService {
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
@ResponseHeader( @ResponseHeader(
name = "Last-Modified", name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" + description = "Date and time the resource was last modified.\n" +
"Used by caches, or in conditional requests."), "Used by caches, or in conditional requests."),
}), }),
@ApiResponse( @ApiResponse(
code = 304, code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of the " + message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
"requested resource."),
@ApiResponse( @ApiResponse(
code = 406, code = 406,
message = "Not Acceptable.\n The requested media type is not supported"), message = "Not Acceptable.\n The requested media type is not supported"),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server ErrorResponse. \n Server error occurred while fetching the group list.") message = "Internal Server ErrorResponse. \n Server error occurred while fetching the list of device groups.")
}) })
@Permission(name = "View All Groups", permission = "/permission/admin/device-mgt/user/groups/list") @Permission(name = "View All Groups", permission = "/permission/admin/device-mgt/user/groups/list")
Response getGroupsOfUser( Response getGroupsOfUser(
@ApiParam( @ApiParam(
name = "username", name = "username",
value = "Username of the user.", value = "The sername of the user.",
required = true) required = true)
@QueryParam("username") String username, @QueryParam("username") String username,
@ApiParam( @ApiParam(
@ -99,11 +99,13 @@ public interface GroupManagementAdminService {
@ApiParam( @ApiParam(
name = "offset", name = "offset",
value = "Starting point within the complete list of items qualified.", value = "Starting point within the complete list of items qualified.",
required = false) required = false,
defaultValue = "0")
@QueryParam("offset") int offset, @QueryParam("offset") int offset,
@ApiParam( @ApiParam(
name = "limit", name = "limit",
value = "Maximum size of resource array to return.", value = "Maximum size of resource array to return.",
required = false) required = false,
defaultValue = "5")
@QueryParam("limit") int limit); @QueryParam("limit") int limit);
} }

16
components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/service/api/admin/UserManagementAdminService.java
Unescape View File

@ -46,23 +46,24 @@ public interface UserManagementAdminService {
consumes = MediaType.APPLICATION_JSON, consumes = MediaType.APPLICATION_JSON,
produces = MediaType.APPLICATION_JSON, produces = MediaType.APPLICATION_JSON,
httpMethod = "POST", httpMethod = "POST",
value = "Change the user password.", value = "Changing the User Password.",
notes = "A user is able to change the password to secure their EMM profile via this REST API.", notes = "The EMM administrator is able to change the password of the users in " +
"the system and block them from logging into their EMM profile using this REST API.",
tags = "User Management Administrative Service") tags = "User Management Administrative Service")
@ApiResponses(value = { @ApiResponses(value = {
@ApiResponse( @ApiResponse(
code = 200, code = 200,
message = "OK. \n Credentials of the user have been updated successfully"), message = "OK. \n Successfully updated the credentials of the user."),
@ApiResponse( @ApiResponse(
code = 400, code = 400,
message = "Bad Request. \n Invalid request or validation error.", message = "Bad Request. \n Invalid request or validation error.",
response = ErrorResponse.class), response = ErrorResponse.class),
@ApiResponse( @ApiResponse(
code = 404, code = 404,
message = "Not Found. \n Resource to be deleted does not exist."), message = "Not Found. \n The resource to be deleted does not exist."),
@ApiResponse( @ApiResponse(
code = 415, code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format."), message = "Unsupported media type. \n The format of the requested entity was not supported."),
@ApiResponse( @ApiResponse(
code = 500, code = 500,
message = "Internal Server Error. \n " + message = "Internal Server Error. \n " +
@ -73,14 +74,15 @@ public interface UserManagementAdminService {
Response resetUserPassword( Response resetUserPassword(
@ApiParam( @ApiParam(
name = "username", name = "username",
value = "Username of the user.", value = "The username of the user." +
"INFO: Add a new user using the POST /users API that is under User Management.",
required = true) required = true)
@PathParam("username") @PathParam("username")
@Size(max = 45) @Size(max = 45)
String username, String username,
@ApiParam( @ApiParam(
name = "domain", name = "domain",
value = "Domain name of the user store.", value = "The domain name of the user store.",
required = false) required = false)
@QueryParam("domain") String domain, @QueryParam("domain") String domain,
@ApiParam( @ApiParam(

Write Preview
Loading…
Cancel
Save