GET /rest/v1/roles

Implementation notes

Handles the GET request of retrieving all roles within Bosch IoT Rollouts. Required permission: ROLE_MANAGEMENT

Get paged list of roles

CURL

$ curl 'https://management-api.host.com/rest/v1/roles?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu*' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

A GET request is used to access the targets

GET /rest/v1/roles?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu* HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/roles?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3Ddocu* HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of roles

content[].id

Number

The technical identifier of the role

content[].name

String

The name of the role

content[]._links.permissions.href

String

Link to list of permissions of the role

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 605

{
  "content" : [ {
    "name" : "Docu role 2",
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/roles/16"
      },
      "permissions" : {
        "href" : "https://management-api.host.com/rest/v1/roles/16/permissions"
      }
    },
    "id" : 16
  }, {
    "name" : "Docu role",
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/roles/15"
      },
      "permissions" : {
        "href" : "https://management-api.host.com/rest/v1/roles/15/permissions"
      }
    },
    "id" : 15
  } ],
  "total" : 3,
  "size" : 2
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/roles

Implementation Notes

Handles the POST request of creating new roles within Bosch IoT Rollouts. The request body must always be a list of roles. Required Permission: ROLE_MANAGEMENT

Create list of roles

CURL

$ curl 'https://management-api.host.com/rest/v1/roles' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '[ {
  "name" : "New Role"
} ]'

Request URL

POST /rest/v1/roles HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Content-Length: 29
Host: management-api.host.com

[ {
  "name" : "New Role"
} ]

Request fields

Path Type Description Allowed Values Mandatory

[]name

String

The name of the role

X

Response (Status 201)

Response fields

Path Type Description Allowed Values

[]name

String

The name of the role

[]id

Number

The description of the entity

Response example

HTTP/1.1 201 Created
Content-Type: application/hal+json
Content-Length: 253

[ {
  "name" : "New Role",
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/roles/9"
    },
    "permissions" : {
      "href" : "https://management-api.host.com/rest/v1/roles/9/permissions"
    }
  },
  "id" : 9
} ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, data volume restriction applies or quota limit exceeded.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/roles/{roleId}

Implementation Notes

Handles the DELETE request of deleting a single role within Bosch IoT Rollouts. Required Permission: ROLE_MANAGEMENT

Deleting a target

CURL

$ curl 'https://management-api.host.com/rest/v1/roles/27' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Request URL

DELETE /rest/v1/roles/27 HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

roleId

The technical identifier of the role

Response (Status 200)

Response example

HTTP/1.1 200 OK

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/roles/{roleId}

Implementation Notes

Handles the GET request of retrieving a single role within Bosch IoT Rollouts. Required Permission: ROLE_MANAGEMENT

Get single role

CURL

$ curl 'https://management-api.host.com/rest/v1/roles/19' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/roles/19 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

roleId

The technical identifier of the role

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the role

name

String

The name of the role

_links.permissions.href

String

Link to list of permissions of the role

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 253

{
  "name" : "Docu role",
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/roles/19"
    },
    "permissions" : {
      "href" : "https://management-api.host.com/rest/v1/roles/19/permissions"
    }
  },
  "id" : 19
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/roles/{roleId}/permissions

Implementation Notes

Handles the GET request of retrieving the permissions list of a specific role. Required Permission: ROLE_MANAGEMENT

List all permissions of a role

Curl

$ curl 'https://management-api.host.com/rest/v1/roles/23/permissions' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/roles/23/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

roleId

The technical identifier of the role

Request parameter example

GET /rest/v1/roles/23/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of role permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 68

[ "DELETE_TARGET", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/roles/{roleId}/permissions

Implementation Notes

Handles the POST request to add grant permissions to a role. Required Permission: ROLE_MANAGEMENT

Grant permission to a target

Curl

$ curl 'https://management-api.host.com/rest/v1/roles/11/permissions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '[ "READ_REPOSITORY", "CREATE_REPOSITORY", "UPDATE_REPOSITORY", "DELETE_REPOSITORY" ]'

Request URL

POST /rest/v1/roles/11/permissions HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Content-Length: 84
Host: management-api.host.com

[ "READ_REPOSITORY", "CREATE_REPOSITORY", "UPDATE_REPOSITORY", "DELETE_REPOSITORY" ]

Request path parameter

Parameter Description

roleId

The technical identifier of the role

Request fields

Path Type Description Allowed Values Mandatory

[]

Array

List of permissions

X

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of role permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 150

[ "READ_REPOSITORY", "DELETE_TARGET", "UPDATE_REPOSITORY", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET", "DELETE_REPOSITORY", "CREATE_REPOSITORY" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

DELETE /rest/v1/roles/{roleId}/permissions/{permission}

Implementation Notes

Handles the DELETE request of removing permissions from a role. Required Permission: ROLE_MANAGEMENT

Canceling an active action

Curl

$ curl 'https://management-api.host.com/rest/v1/roles/2/permissions/DELETE_REPOSITORY' -i -X DELETE \
    -H 'Accept: application/hal+json'

Request URL

DELETE /rest/v1/roles/2/permissions/DELETE_REPOSITORY HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

roleId

The technical identifier of the role

permission

The type of the permission

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]

Array

list of role permissions

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 68

[ "DELETE_TARGET", "READ_TARGET", "CREATE_TARGET", "UPDATE_TARGET" ]

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

Additional content

Error body

{
  "errorCode": "string",
  "exceptionClass": "string",
  "message": "string",
  "parameters": [
    "string"
  ]
}

Field description

Field

Description

errorCode

A error code/key set by server

exceptionClass

The involved exceptionClass

message

An error message set by the server

parameters

A list of parameters

© Bosch.IO GmbH, all rights reserved Corporate information | Data protection notice | Legal information | Support | Free plans