Device Registration



[tags: DMA,RPRM]

Resource Root

https://localhost:8443/api/rest/devices

Summary


Resources Methods
https://localhost:8443/api/rest/devices

POST  Creates a subscription to call server device registrations.

POST  Creates a device.

GET Retrieves all devices information.

https://localhost:8443/api/rest/devices/delete

POST Delete all devices by types.

https://localhost:8443/api/rest/devices/delete/task

GET Get the ongoing delete task ID [tags: DMA,RPRM] .

https://localhost:8443/api/rest/devices/export-inventory

GET Retrieves information of devices.

https://localhost:8443/api/rest/devices/signaling-alias

https://localhost:8443/api/rest/devices/signaling-alias/{alias-value}

GET Retrieves signaling alias from alias value.

https://localhost:8443/api/rest/devices/{device-identifier}

GET  Read a device.

PUT  Update a devices modifiable attributes.

DELETE  Removes the registration of the device(s) with the Call Server and deletes the device(s) from the Polycom RealPresence DMA system.

https://localhost:8443/api/rest/devices/{device-identifier}/credential

GET Get device's crendital.

https://localhost:8443/api/rest/devices/device-types

GET Get all device types.

https://localhost:8443/api/rest/devices/beacon-identifier-associated-devices

POST Query all devices information by BeaconIDs.

https://localhost:8443/api/rest/devices/default

GET Retrieves default values for devices.

Resources


https://localhost:8443/api/rest/devices


Methods

POST


Creates a subscription to call server device registrations.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-subscription+xml
application/vnd.plcm.plcm-device-subscription+json
application/vnd.plcm.plcm-device-subscription-v2+xml
application/vnd.plcm.plcm-device-subscription-v2+json

Response

Status Representation Description
201 Subscription created successfully
400 text/plain
Bad request

POST


Creates a device.
[tags: DMA]

Request

Representations

application/vnd.plcm.plcm-device-v3+xml
application/vnd.plcm.plcm-device-v3+json
application/vnd.plcm.plcm-device-v4+xml
application/vnd.plcm.plcm-device-v4+json

Response

Status Representation Description
201 Device created successfully
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unable to get permission.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Aliases already exist.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device alias value is not valid.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Signaling address already exists.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Port is required for the signaling address (for example, "1.2.3.4:1720").
The default call signaling port is 1720.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Port is required for the RAS address (for example, "1.2.3.4:1719").
The default RAS port is 1719.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The override-default field was false but the corresponding field was specified with a value other than the default.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
The override-default field was true but the corresponding field was not specified.

GET

Retrieves all devices information.
[tags: DMA,RPRM]

Request

Query Parameters

Name Type Description
username xs:string Return only devices that match the username. A domain and username combination uniquely identifies a user.
domain xs:string Return only devices that are associated with network domain. A domain and username combination uniquely identifies a user.
device-model xs:string Return only devices that match the device model.
device-name xs:string Return only devices that match the device name.
ip-address xs:string Return only devices that match the IP Address.
site xs:string Return only devices that match the site.
admission-policy xs:string Return only devices that match the admission policy.
status xs:string Return only devices that match the status.
service-level xs:string Return only devices that match the class of service.
only-show-devices-in-call xs:string Return only devices that are in active calls.
alias xs:string Return only devices that match the alias.
territory xs:string Return only devices that match the territory.
exception-filter xs:string Return only devices that match the exceptions.
compliance-level xs:string Return only devices that match the compliance level.
is-shared-registration xs:string Return only devices that match the is shared registration; plcm-device-v4 only.
owner xs:string Return only devices that match the owner.
Applied to RPRM, owner means user-uuid or room-uuid. If owner is 'NO_OWNER', then return only devices that have not owner.
limit xs:int
Limit the number of users returned to this number, even if more results match the query.
Note 1: The valid integer range is 1 to 500; values between 501 and 2147483647 will result in the default limit of 500 being used.
Note 2: If the limit value is less than or equal to 0, the default of 500 will be used.
Note 3: If the limit value is greater than 2147483647, the system will respond with "404 Not Found".
This is a framework response that is due to a numeric value that exceeds a integer type.
page xs:int
When limiting the results, this specifies which page/subset of data to view.
Note 1: The valid integer range is 1 to 2147483647.
Note 2: If the page value is less than or equal to 0, the default of 1 will be used.
Note 3: If the page value is greater than 2147483647, the system will respond with "404 Not Found".
This is a framework response that is due to a numeric value that exceeds a integer type.
exact-search xs:boolean
Normally string based searches automatically include wildcards, so if you search by user "bcd" you
could also get user "abcde". Set this parameter to true when the search should be limited to only
return the exact matches.
is-provisioned xs:string Return only devices that are currently provisioned through edge access proxy to RPRM; plcm-device-v4 only.
is-supports-h323 xs:string Return devices that support H.323 signaling protocol; plcm-device-v4 only.
is-supports-sip xs:string Return devices that support SIP signaling protocol; plcm-device-v4 only.
is-supports-poly-evo xs:string Return devices that support Poly EVO signaling protocol; plcm-device-v4 only.

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-list+xml
application/vnd.plcm.plcm-device-list+json
application/vnd.plcm.plcm-device-list-v2+xml
application/vnd.plcm.plcm-device-list-v2+json
application/vnd.plcm.plcm-device-list-v3+xml
application/vnd.plcm.plcm-device-list-v3+json
Device list information successfully retrieved.
Applied to RPRM, plcm-device-list, plcm-device-list-v2 and plcm-device-list-v3 are implemented and according mediaType can be accessed by setting Http Accept.
If there are more one representations, Http Accept must be set with the right one.
304
Device information has not changed since the last retrieval.
Note: The API client must provide the "plcm-device-list" representation's
ETag value in the "If-None-Match" HTTP header to ensure conditional
retrieval. This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a previous,
identical single deivce retrieval in the "If-None-Match" header, then
the HTTP response will contain the device representation in the message
body.

The "plcm-device-list" ETag can be accessed from the initial retrieval result's HTTP
response header. Also, subsequent retrievals require the identical domain and
user name to ensure an equivalent ETag value. This also assumes no other client made changes to
devices on the server.
400 text/plain
Device IP is required, bad request.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unable to get permission.
409 application/vnd.plcm.plcm-error+xml
Device IP is invalid.
400 application/vnd.plcm.plcm-error+xml
The requested search result limit is too large.
404 application/vnd.plcm.plcm-error+xml
Owner cannot be found by UUID.
400 application/vnd.plcm.plcm-error+xml
UUID is invalid.
409 application/vnd.plcm.plcm-error+xml
The owner (UUID) doesn't match the domain and username.

https://localhost:8443/api/rest/devices/delete


Methods

POST

Delete all devices by types.A task to monitor the delete process is created.
[tags: DMA,RPRM]

Request

Query Parameters

Name Type Description
delete-type xs:string Device type to delete. ALL, ACTIVE, or INACTIVE

Response

Status Representation Description
202 application/zip
Command accepted, delete task had started.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unable to get permission.
409 application/vnd.plcm.plcm-error+xml
Device type is invalid.
409 application/vnd.plcm.plcm-error+xml
No device matching search criteria found.
409 application/vnd.plcm.plcm-error+xml
Another delete task is already in progress.

https://localhost:8443/api/rest/devices/delete/task


Methods

GET

Get the ongoing delete task ID
[tags: DMA,RPRM]

Request

Query Parameters

Name Type Description
delete-type xs:string Device type to delete. ALL, ACTIVE, or INACTIVE

Response

Status Representation Description
200 The ongoing delete task found.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unable to get permission.
409 application/vnd.plcm.plcm-error+xml
No ongoing delete task.

https://localhost:8443/api/rest/devices/export-inventory


Methods

GET

Retrieves information of devices.
[tags: RPRM]

Request

Response

Status Representation Description
200 application/zip
Inventory information successfully retrieved
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request information.

https://localhost:8443/api/rest/devices/signaling-alias


https://localhost:8443/api/rest/devices/signaling-alias/{alias-value}


Template Parameters

Name Type Description
alias-value xs:string alias value

Methods

GET

Retrieves signaling alias from alias value.
[tags: DMA]

Request

Query Parameters

Name Type Description
include-sip xs:string Retrieves signaling alias from alias value.

Response

Status Representation Description
200 application/vnd.plcm.plcm-signaling-alias-type+xml
application/vnd.plcm.plcm-signaling-alias-type+json
Signaling alias successfully retrieved from alias value
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Current user does not have permission to request information.

https://localhost:8443/api/rest/devices/{device-identifier}


Template Parameters

Name Type Description
device-identifier xs:string device identifier

Methods

GET


Read a device.
[tags: DMA, RPRM]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device+xml
application/vnd.plcm.plcm-device+json
application/vnd.plcm.plcm-device-v2+xml
application/vnd.plcm.plcm-device-v2+json
application/vnd.plcm.plcm-device-v3+xml
application/vnd.plcm.plcm-device-v3+json
application/vnd.plcm.plcm-device-v4+xml
application/vnd.plcm.plcm-device-v4+json
Device information successfully retrieved.
Applied to RPRM, plcm-device, plcm-device-v2, plcm-device-v3, and plcm-device-v4 are implemented and according MediaType can be accessed by setting Http Accept.
If there are more one representations, Http Accept must be set with the right one.
304
Device information has not changed since the last retrieval.
Note: The API client must provide the "plcm-device" representation's
ETag value in the "If-None-Match" HTTP header to ensure conditional
retrieval. This will improve network performance by reducing bandwidth
consumption.

If the API client chooses to exclude an ETag value from a previous,
identical single deivce retrieval in the "If-None-Match" header, then
the HTTP response will contain the device representation in the message
body.

The "plcm-device" ETag can be accessed from the initial retrieval result's HTTP
response header. Also, subsequent retrievals require the identical domain and
user name to ensure an equivalent ETag value. This also assumes no other client made changes to
devices on the server.
403 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Unable to get permission.
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
No such device
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Alias already exists.
404 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device ID doesn't exist.
409 application/vnd.plcm.plcm-error+xml
application/vnd.plcm.plcm-error+json
Device ID is invalid.

PUT


Update a devices modifiable attributes. Only a subset of the device information can be changed.
[tags: DMA,RPRM_INTERNAL]

Request

Representations

application/vnd.plcm.plcm-endpoint-edit-details+xml
application/vnd.plcm.plcm-endpoint-edit-details+json
application/vnd.plcm.plcm-device-v3+xml
application/vnd.plcm.plcm-device-v3+json
application/vnd.plcm.plcm-device-v4+xml
application/vnd.plcm.plcm-device-v4+json

Response

Status Representation Description
204 Device updated successfully
404 Device not found. The device with the supplied device identifier does not exist on the Call Server.
409
Alias conflict. One of the supplied aliases are already configured on other devices.
409
Malformed alias. One of the supplied aliases has an invalid format.
409
The device does not support H.323, manual aliases cannot be assigned to it.
409
The override-default field was false but the corresponding field was specified with a value other than the default.
409
The override-default field was true but the corresponding field was not specified.
412
The client supplied ETag does not match the device's ETag value on the server. This will normally mean that the client does
not have the latest version of the device information.
428 Device ETag has not been supplied in the "If-Match" header.
409
The alias of forward unconditional is required.
409
The alias of forward no answer/offline is required.
409
The alias of forward busy is required.
403 Unable to get permission.

DELETE


Removes the registration of the device(s) with the Call Server and deletes the device(s) from the Polycom RealPresence DMA system.
[tags: DMA,RPRM]

Response

Status Representation Description
204 Device information successfully deleted
403 application/vnd.plcm.plcm-error+xml
Unable to get permission. User roles required: administrator, provisioner
404 application/vnd.plcm.plcm-error+xml
No such device.

https://localhost:8443/api/rest/devices/{device-identifier}/credential


Template Parameters

Name Type Description
device-identifier xs:string device identifier

Methods

GET

Get device's crendital.
[tags: RPRM]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-credential+xml
application/vnd.plcm.plcm-device-credential+json
Device information successfully retrieved
403 application/vnd.plcm.plcm-error+xml
Unable to get permission.
404 application/vnd.plcm.plcm-error+xml
No such device.
409 application/vnd.plcm.plcm-error+xml
Device ID is invalid.It is required by Integer type

https://localhost:8443/api/rest/devices/device-types


Methods

GET

Get all device types.
[tags: RPRM]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-type-list+xml
application/vnd.plcm.plcm-device-type-list+json
Device information successfully retrieved
403 application/vnd.plcm.plcm-error+xml
Unable to get permission.

https://localhost:8443/api/rest/devices/beacon-identifier-associated-devices


Methods

POST

Query all devices information by BeaconIDs.
[tags: RPRM]

Request

Representations

application/vnd.plcm.plcm-beacon-identity-list+xml
application/vnd.plcm.plcm-beacon-identity-list+json

Response

Status Representation Description
200 application/vnd.plcm.plcm-beacon-pairing-list+xml
application/vnd.plcm.plcm-beacon-pairing-list+json
Device ID list successfully retrieved.
If there are more one representations, Http Accept must be set with the right one.
403 application/vnd.plcm.plcm-error+xml
Unable to get permission.
400 application/vnd.plcm.plcm-error+xml
Beacon ID proximity required.
400 application/vnd.plcm.plcm-error+xml
Beacon ID major required
400 application/vnd.plcm.plcm-error+xml
Beacon ID minor required.
400 application/vnd.plcm.plcm-error+xml
Beacon ID Proximity does not support.
400 application/vnd.plcm.plcm-error+xml
No device associated with this beacon.
400 application/vnd.plcm.plcm-error+xml
Beacon ID is invalid.

https://localhost:8443/api/rest/devices/default


Methods

GET

Retrieves default values for devices.
[tags: DMA]

Response

Status Representation Description
200 application/vnd.plcm.plcm-device-defaults+xml
application/vnd.plcm.plcm-device-defaults+json
Default values successfully retrieved
403 application/vnd.plcm.plcm-error+xml
Unable to get permission.