Users

This chapter focuses on services for the users.

get Get all users

A GET to /users returns all the users.

HTTP request

GET /api/rest/latest/users?page=2&size=1 HTTP/1.1
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

sort

which attributes of the returned entities should be sorted on (optional)

fields

which fields of the elements should be returned (optional)

type

which type of the element should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 894

{
  "_embedded" : {
    "users" : [ {
      "_type" : "user",
      "id" : 486,
      "login" : "User-1",
      "active" : true,
      "group" : "User",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/users/486"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/rest/latest/users?page=0&size=1"
    },
    "prev" : {
      "href" : "http://localhost:8080/api/rest/latest/users?page=1&size=1"
    },
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users?page=2&size=1"
    },
    "next" : {
      "href" : "http://localhost:8080/api/rest/latest/users?page=3&size=1"
    },
    "last" : {
      "href" : "http://localhost:8080/api/rest/latest/users?page=4&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 5,
    "totalPages" : 5,
    "number" : 2
  }
}

Response fields

Path Type Description

_embedded.users

Array

the list of elements for that page

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the user is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

post Create user

A POST to /users creates a new user.

HTTP request

POST /api/rest/latest/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 214
Host: localhost:8080

{
  "_type" : "user",
  "first_name" : "Charles",
  "last_name" : "Dupond",
  "login" : "User-1",
  "password" : "123456",
  "email" : "charlesdupond@aaaa.aa",
  "group" : "User",
  "can_delete_from_front" : true
}

Request fields

Path Type Description

_type

String

the type of the entity

first_name

String

the first name of the user (optional)

last_name

String

the last name of the user

login

String

the login of the user

password

String

the password of the user

email

String

the email address of the user (optional)

group

String

the group to which the user belongs ("Admin", "User" or "TechnicalAccount")

can_delete_from_front

Boolean

whether the user can delete library entities from the front-end with the Squash TM Premium plugin

Query parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 566

{
  "_type" : "user",
  "id" : 987,
  "first_name" : "Charles",
  "last_name" : "Dupond",
  "login" : "User-1",
  "email" : "charlesdupond@aaaa.aa",
  "active" : true,
  "group" : "User",
  "can_delete_from_front" : true,
  "teams" : [ ],
  "last_connected_on" : "2018-03-05T11:00:00.000+00:00",
  "created_by" : "admin",
  "created_on" : "2017-07-04T10:00:00.000+00:00",
  "last_modified_by" : "admin",
  "last_modified_on" : "2017-07-05T10:00:00.000+00:00",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/987"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the user

active

Boolean

whether the user is activate or not

teams

Array

the team of the user participate

last_connected_on

String

the date of this user was last connected

created_by

String

the user who created this user account

created_on

String

the date of this user account was created

last_modified_by

String

the user who last modified this user account

last_modified_on

String

the date of this user account was last modified

_links

Object

related links

Links

Relation Description

self

link to this user

get Get user

A GET to /users/{id} returns the user with the given id.

Path parameters

Table 1. /api/rest/latest/users/{id}
Parameter Description

id

the id of the user

HTTP request

GET /api/rest/latest/users/486 HTTP/1.1
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 566

{
  "_type" : "user",
  "id" : 486,
  "first_name" : "Charles",
  "last_name" : "Dupond",
  "login" : "User-1",
  "email" : "charlesdupond@aaaa.aa",
  "active" : true,
  "group" : "User",
  "can_delete_from_front" : true,
  "teams" : [ ],
  "last_connected_on" : "2018-02-11T11:00:00.000+00:00",
  "created_by" : "admin",
  "created_on" : "2017-07-04T10:00:00.000+00:00",
  "last_modified_by" : "admin",
  "last_modified_on" : "2017-07-05T10:00:00.000+00:00",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

the id of the user

first_name

String

the first name of the user

last_name

String

the last name of the user

login

String

the login of the user

email

String

the email address of the user

active

Boolean

whether the user is activate or not

group

String

the group to which the user belongs ("Admin", "User" or "TechnicalAccount")

can_delete_from_front

Boolean

whether the user can delete library entities from the front-end with the Squash TM Premium plugin

teams

Array

the team of the user participate

last_connected_on

String

the date of this user was last connected

created_by

String

the user who created this user account

created_on

String

the date of this user account was created

last_modified_by

String

the user who last modified this user account

last_modified_on

String

the date of this user account was last modified

_links

Object

related links

Links

Relation Description

self

link to this user

patch Modify user

A PATCH to /users/{id} modifies the user with the given id.

Path parameters

Table 1. /api/rest/latest/users/{id}
Parameter Description

id

the id of the user

HTTP request

PATCH /api/rest/latest/users/987 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 236
Host: localhost:8080

{
  "_type" : "user",
  "first_name" : "Charles",
  "last_name" : "Dupond",
  "login" : "User-42",
  "password" : "123456",
  "email" : "charlesdupond@bbbb.bb",
  "active" : false,
  "group" : "User",
  "can_delete_from_front" : false
}

Request fields

Path Type Description

_type

String

the type of the entity

first_name

String

the first name of the user

last_name

String

the last name of the user

login

String

the login of the user

password

String

the password of the user

email

String

the email address of the user

active

Boolean

whether the user is activate or not

group

String

the group to which the user belongs ("Admin", "User" or "TechnicalAccount")

can_delete_from_front

Boolean

whether the user can delete library entities from the front-end with the Squash TM Premium plugin

Query parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 569

{
  "_type" : "user",
  "id" : 987,
  "first_name" : "Charles",
  "last_name" : "Dupond",
  "login" : "User-42",
  "email" : "charlesdupond@bbbb.bb",
  "active" : false,
  "group" : "User",
  "can_delete_from_front" : false,
  "teams" : [ ],
  "last_connected_on" : "2018-03-05T11:00:00.000+00:00",
  "created_by" : "admin",
  "created_on" : "2017-07-04T10:00:00.000+00:00",
  "last_modified_by" : "admin",
  "last_modified_on" : "2017-07-05T10:00:00.000+00:00",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/987"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the user

teams

Array

the team of which the user is a member

last_connected_on

String

the date of this user was last connected

created_by

String

the user who created this user account

created_on

String

the date of this user account was created

last_modified_by

String

the user who last modified this user account

last_modified_on

String

the date of this user account was last modified

can_delete_from_front

Boolean

whether the user can delete library entities from the front-end with the Squash TM Premium plugin

_links

Object

related links

Links

Relation Description

self

link to this user

delete Delete user

A DELETE to /users/{ids} deletes one or several users with the given id(s).

Path parameters

Table 1. /api/rest/latest/users/{ids}
Parameter Description

ids

the list of ids of the users

HTTP request

DELETE /api/rest/latest/users/169,189 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

get Get user subscribed teams

A GET to /users/{id}/teams returns all the subscribed teams of the user with the given id.

Path parameters

Table 1. /api/rest/latest/users/{id}/teams
Parameter Description

id

the id of the user

HTTP request

GET /api/rest/latest/users/486/teams HTTP/1.1
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1120

{
  "_embedded" : {
    "teams" : [ {
      "_type" : "team",
      "id" : 567,
      "name" : "Team A",
      "description" : "<p>black panther</p>",
      "created_by" : "admin",
      "created_on" : "2017-07-04T10:00:00.000+00:00",
      "last_modified_by" : "admin",
      "last_modified_on" : "2017-07-05T10:00:00.000+00:00",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/teams/567"
        }
      }
    }, {
      "_type" : "team",
      "id" : 568,
      "name" : "Team B",
      "description" : "<p>black widow</p>",
      "created_by" : "admin",
      "created_on" : "2017-07-04T10:00:00.000+00:00",
      "last_modified_by" : "admin",
      "last_modified_on" : "2017-07-05T10:00:00.000+00:00",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/teams/568"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486/teams?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Response fields

Path Type Description

_embedded.teams

Array

the teams of this user

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the user is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

post Subscribe to teams

A POST to /users/{userId}/teams, including teamIds as request parameters, subscribes the user with the given id to these teams.

Path parameters

Table 1. /api/rest/latest/users/{userId}/teams
Parameter Description

userId

the id of the user

HTTP request

POST /api/rest/latest/users/987/teams?teamIds=486,487 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

teamIds

the list of ids of the teams

delete Unsubscribe from teams

A DELETE to /users/{userId}/teams, including teamIds as request parameters, unsubscribes the user with the given id from these teams.

Path parameters

Table 1. /api/rest/latest/users/{userId}/teams
Parameter Description

userId

the id of the user

HTTP request

DELETE /api/rest/latest/users/987/teams?teamIds=486,487 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Query parameters

Parameter Description

teamIds

the list of ids of the teams

get Get user clearances

A GET to /users/{id}/clearances returns the clearances grouped by profiles for the user with the given id.

Path parameters

Table 1. /api/rest/latest/users/{id}/clearances
Parameter Description

id

the id of the user

HTTP request

GET /api/rest/latest/users/486/clearances HTTP/1.1
Accept: application/json
Host: localhost:8080

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1540

{
  "content" : {
    "test_designer" : {
      "_type" : "profile",
      "id" : 7,
      "name" : "TestDesigner",
      "type" : "system",
      "projects" : [ {
        "_type" : "project",
        "id" : 367,
        "description" : "<p>This project is the main sample project</p>",
        "label" : "Main Sample Project",
        "name" : "proj1",
        "attachments" : [ ],
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/projects/367"
          }
        }
      }, {
        "_type" : "project",
        "id" : 368,
        "description" : "<p>This project is the main sample project</p>",
        "label" : "Main Sample Project",
        "name" : "proj2",
        "attachments" : [ ],
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/projects/368"
          }
        }
      } ]
    },
    "validator" : {
      "_type" : "profile",
      "id" : 9,
      "name" : "Validator",
      "type" : "system",
      "projects" : [ {
        "_type" : "project",
        "id" : 369,
        "description" : "<p>This project is the main sample project</p>",
        "label" : "Main Sample Project",
        "name" : "proj3",
        "attachments" : [ ],
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/projects/369"
          }
        }
      } ]
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486/clearances"
    }
  }
}

Response fields

Path Type Description

content

Object

contains clearances grouped by profiles

content.validator

Object

contains the profile attributes (example of the validator profile)

content.validator._type

String

the type of the entity

content.validator.id

Number

the id of the profile

content.validator.name

String

the name of the profile

content.validator.type

String

system if the profile is a system profile, custom if the profile is a custom profile

content.validator.projects

Array

the list of projects linked to the profile

_links

Object

related links

Links

Relation Description

self

the link to this user clearances

Get user clearances (deprecated)

A GET to /users/{id}/permissions returns the clearances grouped by profiles for the user with the given id.

This endpoint is still functional but is deprecated. Please use the more comprehensive /users/{id}/clearances endpoint instead.

Path parameters
Table 1. /api/rest/latest/users/{id}/permissions
Parameter Description

id

the id of the user
HTTP request
GET /api/rest/latest/users/486/permissions HTTP/1.1
Accept: application/json
Host: localhost:8080
Query parameters
Parameter Description

fields

which fields of the elements should be returned (optional)
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1220

{
  "content" : {
    "test_designer" : [ {
      "_type" : "project",
      "id" : 367,
      "description" : "<p>This project is the main sample project</p>",
      "label" : "Main Sample Project",
      "name" : "proj1",
      "attachments" : [ ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/projects/367"
        }
      }
    }, {
      "_type" : "project",
      "id" : 368,
      "description" : "<p>This project is the main sample project</p>",
      "label" : "Main Sample Project",
      "name" : "proj2",
      "attachments" : [ ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/projects/368"
        }
      }
    } ],
    "validator" : [ {
      "_type" : "project",
      "id" : 369,
      "description" : "<p>This project is the main sample project</p>",
      "label" : "Main Sample Project",
      "name" : "proj3",
      "attachments" : [ ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/projects/369"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486/permissions"
    }
  }
}
Links
Relation Description

self

the link to this user clearances

post Add clearances to user

A POST to /users/{userId}/clearances/{profileId}/projects/{projectIds} adds the specified project ids to the profile identified by {profileId} for the user with the given {userId}.

Path parameters

Table 1. /api/rest/latest/users/{userId}/clearances/{profileId}/projects/{projectIds}
Parameter Description

userId

the id of the user

profileId

the id of the profile

projectIds

the ids of the projects

HTTP request

POST /api/rest/latest/users/486/clearances/9/projects/369 HTTP/1.1
Accept: application/json
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 659

{
  "content" : {
    "test_designer" : {
      "_type" : "profile",
      "id" : 4,
      "name" : "TestDesigner",
      "type" : "system",
      "projects" : [ {
        "_type" : "project",
        "id" : 369,
        "description" : "<p>This project is the main sample project</p>",
        "label" : "Main Sample Project",
        "name" : "proj3",
        "attachments" : [ ],
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/projects/369"
          }
        }
      } ]
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486/clearances"
    }
  }
}

Response fields

Path Type Description

content

Object

contains the added clearance

content.test_designer

Object

contains the profile attributes (example of the test designer profile)

content.test_designer._type

String

the type of the entity

content.test_designer.id

Number

the id of the profile

content.test_designer.name

String

the name of the profile

content.test_designer.type

String

system if the profile is a system profile, custom if the profile is a custom profile

content.test_designer.projects

Array

the list of projects linked to the profile

_links

Object

related links

Links

Relation Description

self

the link to this user clearances

Add clearances to user (deprecated - only for system profile)

A POST to /users/{userId}/permissions/{permissionGroup} adds the given system profile to the user with the given id.

The possible {permissionGroup} values are test_editor, project_viewer, project_manager, test_runner, test_designer, advanced_tester and validator.

This endpoint is still functional but is deprecated. Please use the more comprehensive /users/{userId}/clearances/{profileId}/projects/{projectIds} endpoint instead.

Path parameters
Table 1. /api/rest/latest/users/{userId}/permissions/{permissionGroup}
Parameter Description

userId

the id of the user

permissionGroup

the profile
HTTP request
POST /api/rest/latest/users/486/permissions/test_designer?ids=369 HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: localhost:8080
Query parameters
Parameter Description

ids

the ids of the projects
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 510

{
  "content" : {
    "test_designer" : [ {
      "_type" : "project",
      "id" : 369,
      "description" : "<p>This project is the main sample project</p>",
      "label" : "Main Sample Project",
      "name" : "proj3",
      "attachments" : [ ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/projects/369"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/users/486/permissions"
    }
  }
}
Links
Relation Description

self

the link to this user clearances

delete Delete clearances for user

A DELETE to /users/{userId}/clearances/{projectIds} deletes one or several clearances for the given user and given project ids (comma-separated).

Path parameters

Table 1. /api/rest/latest/users/{userId}/clearances/{projectIds}
Parameter Description

userId

the id of the user

projectIds

the ids of the project to remove

HTTP request

DELETE /api/rest/latest/users/486/clearances/369,370 HTTP/1.1
Accept: application/json
Host: localhost:8080

Delete clearances for user (deprecated)

A DELETE to /users/{id}/permissions deletes one or more clearances for the given user. The project ids should be provided as a comma-separated list.

This endpoint is still functional but is deprecated. Please use the more comprehensive /users/{userId}/clearances/{projectIds} endpoint instead.

Path parameters
Table 1. /api/rest/latest/users/{id}/permissions
Parameter Description

id

the id of the user
HTTP request
DELETE /api/rest/latest/users/486/permissions?ids=369 HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: localhost:8080
Query parameters
Parameter Description

ids

the ids of the projects