Roles Resource

Waterline Data uses roles to indicate what data resources from the catalog are available to each user. User roles determine what actions each user can perform for metadata management inside Waterline Data. Endpoints under /role allow creation of new roles and modification of existing roles. To associate roles to users, use a PUT request to /user/{key}.
A user with the admin role can create or modify roles with requests to the role endpoint. User roles are defined by the Role object, which has these components:

  • A list of data sources that role can access.
  • A list of of tag domains that role can access.
  • An access level.
  • A unique identifying key value, assigned on creation.
By default, Waterline Data provides these access level definitions:
  • administrator
  • steward
  • analyst
  • guest

GET /v2/role

A GET request to the /role endpoint retrieves a list of roles.

Response Body
media type data type description
application/json array of Role (JSON) A list of Role objects in JSON format.

Example

Request
GET /v2/role
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
[ {
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Administrator",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
} ]

POST /v2/role

A POST request to the /role endpoint creates a new role definition.

Request Body
media type data type description
application/json Role (JSON) A JSON object containing the new role information, including at least a role name.
Response Body
media type data type description
application/json Role (JSON) The new Role object in JSON format, containing the assigned unique identifying key.

Example

Request
POST /v2/role
Content-Type: application/json
Accept: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Administrator",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Steward",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}

GET /v2/role/byname

A GET request to the /role/byname endpoint retrieves a list of defined user roles.

Request Parameters
name type description
name query The role name.
Response Body
media type data type description
application/json Role (JSON) The Role object in JSON format, including the unique identifier of the role.

Example

Request
GET /v2/role/byname
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Steward",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}

DELETE /v2/role/{key}

A DELETE request to the /role/{key} endpoint removes an existing role definition.

Request Parameters
name type description
key path The unique identifier of a role.

Example

Request
DELETE /v2/role/{key}
Content-Type: */*

                
...
Response
HTTP/1.1 204 No Content

GET /v2/role/{key}

A GET request to the /role/{key} endpoint retrieves a specific roles.

Request Parameters
name type description
key path The unique identifier of a role, as assigned on creation.
Response Body
media type data type description
application/json Role (JSON) The Role object in JSON format.

Example

Request
GET /v2/role/{key}
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Administrator",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}

PUT /v2/role/{key}

A PUT request to the /role/{key} endpoint updates an existing role definition.

Request Parameters
name type description
key path The unique identifier of a role.
Request Body
media type data type description
application/json Role (JSON) A JSON object containing the new role-definition information. Properties that are not present are not changed.
Response Body
media type data type description
application/json Role (JSON) The updated Role object, in JSON format.

Example

Request
PUT /v2/role/{key}
Content-Type: application/json
Accept: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Administrator",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}
Response
HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "metadataAccessOption" : "...",
  "jobTemplateCreationAllowed" : true,
  "virtualFolderKeys" : [ "...", "..." ],
  "name" : "...",
  "domainKeys" : [ "...", "..." ],
  "dataAccessOption" : "...",
  "jobExecutionAllowed" : true,
  "defaultRole" : true,
  "accessLevel" : "Steward",
  "resourceReadAccessLevel" : "...",
  "dataSourceKeys" : [ "...", "..." ],
  "datasetKeys" : [ "...", "..." ],
  "timeOfLastChange" : 12345,
  "timeOfCreation" : 12345,
  "key" : "...",
  "description" : "...",
  "type" : "...",
  "restricted" : [ "...", "..." ],
  "viewAble" : [ "...", "..." ],
  "updateable" : [ "...", "..." ],
  "richDescription" : "...",
  "score" : 12345.0,
  "customProperties" : [ {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  }, {
    "description" : "...",
    "value" : { },
    "facetAble" : true,
    "name" : "...",
    "type" : "...",
    "displayName" : "..."
  } ]
}