Creating groups and group membership. The GenomeSpace Data Manager uses groups to provide/restrict access by other users to GenomeSpace files and directories.

Nearly all services require a login as a security measure; user registration and password reset are two that do not. Most services use the logged-in user to associate or limit access to the serviceable entity. For example a created user profile will be associated with the logged-in user, implicitly.

Client Requirements

The IdentityServer REST interface is accessed using HTTPS POST, GET, PUT, and DELETE.

JSON is used to pass application data to and from the server, with a few exceptions as indicated below by the HTTP request header requirements.

The REST calls that need a user login will require the HTTP header Cookie: gs-token=A_valid_token. The valid token is to have been obtained in a prior login using the IdentityServer's OpenId or HTTP Basic Authentication protocol.

General REST Implementation Details

The URLs below need to be prefixed with an appropriate GenomeSpace Identity Server URL, which is obtained at runtime as described in the Adopters page. An example is https://identity.genomespace.org/identityServer/.

REST failure responses indicating generic errors are not shown. Examples are 405 for Incorrect HTTP verb, 401 for Not logged in, 409 for Internal server error including incorrectly formatted json, and 403 for operations forbidden due to access restriction, such as deleting another user's user profile.

In general it is desirable (but optional) for tools to add a header (or request parameter, or cookie, any of these forms can be used) gs-toolname=MyToolName to all their requests. This is optional but identifies which tool is making a request which permits more detailed usage reporting within the GenomeSpace system.

User Services

Registration Request

Creates a request for GenomeSpace user account. An email is sent to the user containing a url. Account registration is completed when an HTTP GET is done on that url.

Please note, the previous single-step registration is deprecated, and will become unusable in the near future.

A login is not required. Username and password are validated (40 chars max, restricted char set, and username uniqueness) and a 409 status with message is returned if there is a problem.

Response

Registration Completion

Finalizes a registration request. The uuid parameter comes from an email that was sent to the user.

A login is not required.

Request

Required headers: none

Verb

URL

Body

GET

usermanagement/register/pendingUuid/{uuid}

[none]

Response

Status

Status Code

Body

See Other

303

Redirects to an identityServer message page containing a success or fail message.

Reset Password

The GenomeSpace server will assign a time-limited, one-use temporary password to the user, and will email it to the email address on record for that user. The regular password is not changed by this action; user can change their password once logged in with the temporary password.

Request

Required headers: none

{username_or_email} is either the GenomeSpace username, or the registered user's email address.

Verb

URL

PUT

usermanagement/resetpassword/{username_or_email}

Response

Status

Status Code

Reason

OK

204

Fail

404

No such user, etc.

Get Remaining Time on Token

GenomeSpace generates a string upon successful login called a token, and it is typically put in a cookie or in ~/.gs. This service returns the amount of time remaining on a token.

The token to be examined may come from either a cookie or URL query parameter. No user login is necessary.

Request

Required headers: Accept: text/plain

Verb

URL

Source of token

GET

usermanagement/utility/token/remainingTime

gs-token cookie

GET

usermanagement/utility/token/remainingTime?token={token}

query parameter

Response

Status

Status Code

Body

OK

200

[Plain text, not JSON] The number of milliseconds remaining.

Get Username from Token

A given token (a GenomeSpace generated string) is assigned to a user. This service returns the username for a token.

The token to be examined may come from either a cookie or URL query parameter. No user login is necessary.

Request

Required headers: Accept: text/plain

Verb

URL

Source of token

GET

usermanagement/utility/token/username

gs-token cookie

GET

usermanagement/utility/token/username?token={token}

query parameter

Response

Status

Status Code

Body

OK

200

[Plain text, not JSON] The username.

Get All GenomeSpace Usernames

Returns all GenomeSpace usernames. A login is required for security but does not affect the results.

Request

Required headers: Accept: application/json

Verb

URL

GET

selfmanagement/usernames

Response

Status

Status Code

Body

OK

200

{"usernames":["bob","ted","alice","jane"]}

Find matching GenomeSpace Usernames by Email

Returns all GenomeSpace usernames matching the email provided. A login is required for security but does not affect the results.

User Profile Services

User Profiles are per-user persistent data kept as database records. A user profile has an internal UUID but is functionally identified by client-defined optional attributes. A client should always define one attribute called "module" which serves as a namespace, having the value of the Java package, or client's url domain name.

Create User Profile

Creates an instance of user profile. Requires a GenomeSpace login, and the username json parameter must match the login (404 results otherwise).

The HTTP reply will contain the url of the created resource. The 36 character UUID profile id is the last component in the created URL.

Response

Get User Profile by User

Gets all profiles for a user, or applies filtering to get only some. Optional attributes specify which subset of profiles should be fetched. If no optional attributes are specified then all the user's profiles are returned. If one or more are specified then only profiles having a matching optional attribute are returned.

If logged-in user is not a member and non-member-readable=false
{"id":"b87c3380-502f-4779-b1ce-f3316665ffa6","self-administered":"false",
"description":"some description","name":"group0","non-member-readable":"false",
"members":[]}

OK

204

No such group exists

Fail

409

User is not a member of the group

Get groups for User

Returns the group attributes (no membership info) of all groups whose membership includes the user. A login is required for security but does not affect the results.

Get my readable groups

Returns the group attributes (no membership info) of either groups whose membership includes the logged-in user, or groups that are non-member readable. Login is required and it determines the membership username that gets used.

Request

Required headers: Accept: application/json

Verb

URL

GET

groupmanagement/readable/group

Response

The return datatype is JSON. In the following example the logged in user is a member of group0 and gs-public, but not of group1.

Get my manageable groups

Returns the group attributes (no membership info) of either groups whose administrators includes the logged-in user, or groups that are self-administrating and whose membership includes the logged-in user. Login is required and it determines the membership username that gets used.

Request

Required headers: Accept: application/json

Verb

URL

GET

groupmanagement/manageable/group

Response

The return datatype is JSON. In the following example the logged in user is an admin of group0, and only a member of the self-administered group1.

Update group

Updates the attributes of a group. If members are specified then the membership is updated too, provided at least one member remains and at least one administrator. The logged-in user must be an administrator of the group. A self-administered group allows non-administrators to update membership but not the group attributes.

Request

Required headers: Content-Type: application/json

Verb

URL

Body

PUT

groupmanagement/group

{"description":"Describes it","id":"5035080c-4afe-4c84-af55-71ebf8a7741b",
"name":"My updated group name for this group",
"non-member-readable":"false","self-administered":"true"}

PUT

groupmanagement/group

{"description":"Describes it","id":"5035080c-4afe-4c84-af55-71ebf8a7741b",
"name":"My updated group name for this group",
"non-member-readable":"false","self-administered":"true",
members":[{"is-admin":"true","username":"user2"},
{"is-admin":"false","username":"user0"}]}

Response

Status

Code

Body

OK

200

(none)

Fail

409

Username is not an administrator

Fail

409

Group does not exist

Delete group

Deletes the group. The logged-in user must be an administrator of the group.