| 

Back

RESTful Access to Identity Server (version beta 4.1)

Introduction

Introduction

The Identity Server provides REST services for

  1. User registration, password reset, change password and email.
  2. Saving and retrieving per-user persistent data with User Profiles.
  3. 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.

Request

All JSON fields shown here are required.  Required headers: Accept: text/html, Content-Type: application/json

Verb URL Body
POST usermanagement/register/initial {"username":"my_name",
"email":"my_name@my.org",
"password":"xyzzy"}

Response

Status Status Code Body
OK 200  
Fail 409

username already exists, invalid username characters, etc.

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.

Request

Required headers: Accept: application/json

Verb URL
GET selfmanagement/email/{email address}

Response

Status Status Code Body
OK 200

[
    {
        "username": "junit_restestG_1349185132419_user3",
        "email": "test@test.com",
        "usernameLowercase": "junit_restestg_1349185132419_user3"
    },
    {
        "username": "junit_test_1363614700804_user3",
        "email": "test@test.com",
        "usernameLowercase": "junit_test_1363614700804_user3"
    }

]

Get User Info

Returns the logged-in user's registration info.

Request

Required headers: Accept: application/json

Verb URL Username source
GET selfmanagement/user gs-token cookie
GET selfmanagement/user/{username} query parameter (must match the login)

Response

Status Status Code Body
OK 200 {"username":"bob","registrationDate":"Fri, Feb 29, 2011 at 04:53:03",
"token":"ZhPH20zL87EpXS+a5bQe8cD\/b+fk1e79","email":"email@none.org",
"tokenExpiration":"1317709404123","usernameLowercase":"bob","roles":"public",
"sysid":"08511269-8d24-4a94-9e57-59c699790c0f","version":"16"}

Change Email or Password

Allows a GenomeSpace user to change his/her password or email address. A user login is required.

Request

Required headers: Content-Type: application/json

JSON should contain only the fields that change, i.e. only password, only email, or both.

Verb URL Body Username source
PUT selfmanagement/user "{"password":"XYZZY",
"email":"new@email.org"}		 gs-token cookie
PUT selfmanagement/user/{username} "{"password":"XYZZY",
"email":"new@email.org"}		 query parameter (must match login)

 

Response

Status Status Code Body
OK 200 [No content]

Delete User Record

Allows a GenomeSpace user to delete his/her GenomeSpace account. A user login is required.

Request

Required headers: none

Verb URL Username source
DELETE selfmanagement/user gs-token cookie
DELETE selfmanagement/user/{username} query parameter (must match login)

Response

Status Status Code Body
OK 201 [No content]

Get User Action Log (history)

Get the user action log entries for the current user over a specified time period.  Requires user be logged in.

Request

Required headers: Accept: application/json.  Dates should be formatetd as "yyyy-mm-dd" (e.g. '2013-08-12'   for August 12, 2013)

Verb URL Username source
GET userlog/userjson/{from date}/{to date} gs-token cookie

Response

Status Status Code Body
OK 200 
[{"username": "ted", "entity": "GSUI web application", "timestamp": "2013-08-16 12:46", "function": "LOGIN", "module": "GSUI"},
	{"username": "ted", "entity": "GetWebTools", "timestamp": "2013-08-16 12:46", "function": "READ", "module": "ATM"}]

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.

Request

Required headers: Content-Type: application/json

Verb URL Body
POST /selfmanagement/profile {"username":"junit_userProfile_1319573589201_user5",
"value":"some persisted string, possibly json",
"module":"org.yourOrganiztion.yourProject.yourModule",
"myOptionalAttr1":"example1",
"myOptionalAttr2":"example2"}/td>

Response

Status Status Code Sample HTTP header attribute
OK 201 Location: https://identity.genomespace.org:8444/identityServer/
groupmanagement/group/108129df-aa59-4da0-ae6b-0e3c1323684c

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.

Request

Required headers: Accept: application/json

Verb URL Comment
GET selfmanagement/profile/user/{username} Returns all profiles for the user
GET selfmanagement/profile/user/{username}?
{optionalAttributeName1}={attr1}&
{optionalAttributeName2}={attr2}...		 Returns profiles for user having attr1 and attr2

Response

Status Status Code Sample json
OK 200 {"profiles":[{"timestamp":"1318098869739","username":"gs_user1",
"value":"test value 0","uuid":"30662a95-8002-4e68-a54d-fd0864dcc407"},
{"timestamp":"1318098869843","username":"gs_user1",
"myattribute":"myvalue","value":"test value 1",
"uuid":"43e72992-0238-49ed-8b63-0ced11e4bb40"}]}
OK 404 No matching profiles found

Get User Profiles by User

Gets the one specified profile, or returns 404 if profile not found.

Request

Required headers: Accept: application/json

Verb URL
GET selfmanagement/profile/{profileId}

Response

Status Status Code Sample json
OK 200 {"timestamp":"1318098867961","username":"gs_user0",
"value":"test value 0","uuid":"986c6d73-970b-45b4-b064-4a9b9615a801"}
OK 404 No matching profiles found

Update User Profile

Changes an existing user profile record.

Update permits the removal of optional attributes. All optional attributes to be kept must be provided in the update json, along with the UUID.

To change just the persisted value, an alternative is to "re-create" a user profile using POST and specifying exactly the same optional attributes, and that will overwrite an existing profile.

Request

Required headers: Content-Type: application/json

Verb URL Body
PUT selfmanagement/profile {"username":"junit_userProfile_1319573589201_user5",
"value":"some persisted string, possibly json",
"module":"org.yourOrganiztion.yourProject.yourModule",
"uuid":"c14082c7-794a-44da-a252-54296d83db6b"}

Response

Status Status Code Sample HTTP header attribute
OK 204

Delete User Profile

Request

Required headers: none

Verb URL
DELETE selfmanagement/profile/{profileId}

Response

Status Status Code Sample HTTP header attribute
OK 204

Group Management Service

Get All Group Names and Group Ids

Returns all group names and their ids. A login is required for security but does not affect the results.

Request

Required headers: Accept: application/json

Verb URL
GET groupmanagement/groups

Responses

Status Status Code JSON returned
OK 200 {"groups":[{"id":"eafc1a3a-4475-4282-ac64-6c486ee064d1",
"name":"junit_restestG_1319573546874_group0"},
{"id":"8124d580-a677-4957-af67-1e71445945f8",
"name":"DmClientTestGroup"}]}

Get Group Ids for User

Returns the groupId of all groups whose membership includes the specified user. A login is required for security but does not affect the results.

Request

Required headers: Accept: application/json

Verb URL
GET groupmanagement/user/{username}/groupids

Response

OK 200 {"groupids":["b87c3380-502f-4779-b1ce-f3316665ffa6","8c0f3816-9e5e-4239-a842-79ecab53ca82",
"5035080c-4afe-4c84-af55-71ebf8a7741b","e67fe11d-323d-470c-9fb8-5426ed4ca804","gs-public"]}

Create Group

Creates a group. If no members are specified, adds the logged-in user as the first member and first group administrator. If members are specified, at least one must be flagged as the administrator.

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

Request

Required headers: Content-Type: application/json

Verb URL Body
POST groupmanagement/group {"self-administered":"false","description":"Your string of choice",
"name":"group0","non-member-readable":"false"}
POST groupmanagement/group {"self-administered":"true","description":"Your string of choice",
"name":"group0","non-member-readable":"false",
"members":[{"username":"user0","is-admin":"true"},
{"username":"user1","is-admin":"false"}]}

Response

Status Status Code Detail
OK 201 Location: https://identity.genomespace.org:8444/identityServer/
groupmanagement/group/108129df-aa59-4da0-ae6b-0e3c1323684c
Fail 409 Group having name 'group0' already exists
Fail 409 Unknown GenomeSpace user
Fail 409 List of users is missing is-admin=true

Get group

Returns the attributes of the group. Will also return membership if the logged-in user is a member of the group, or if the group is non-member readable. Otherwise the membership will be empty.

Request

Required headers: Accept: application/json

Verb URL
GET groupmanagement/group/{groupid}

{groupid} is the UUID generated when the group was created.

Response

Status Status Code Example
OK 200 {"id":"b87c3380-502f-4779-b1ce-f3316665ffa6","self-administered":"false",
"description":"some description","name":"group0","non-member-readable":"false",
"members":[{"username":"user0","is-admin":"true"}]}
OK 200 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.

Request

Required headers: Accept: application/json

Verb URL
GET groupmanagement/user/{username}/group

Response

The return datatype is JSON.

Status Code Body
OK 200 {"groups":[{"id":"b87c3380-502f-4779-b1ce-f3316665ffa6","self-administered":"false",
"description":"Desc 0","name":"group0","non-member-readable":"false",
{"id":"8c0f3816-9e5e-4239-a842-79ecab53ca82","self-administered":"false",
"description":"the description","name":"group1","non-member-readable":"false",
{"id":"gs-public","self-administered":"false",
"description":"GenomeSpace Public Group","name":"gs-public","non-member-readable":"false"}
Fail 409 username is not a registered user

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.

Status Code Body
OK 200 {"groups":[{"id":"b87c3380-502f-4779-b1ce-f3316665ffa6","self-administered":"false",
"description":"Desc 0","name":"group0","non-member-readable":"false",
{"id":"8c0f3816-9e5e-4239-a842-79ecab53ca82","self-administered":"false",
"description":"the description","name":"group1","non-member-readable":"true",
{"id":"gs-public","self-administered":"false",
"description":"GenomeSpace Public Group","name":"gs-public","non-member-readable":"false"}
Fail 409 username is not a registered user

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.

Status Code Body
OK 200 {"groups":[{"id":"b87c3380-502f-4779-b1ce-f3316665ffa6","self-administered":"false",
"description":"Desc 0","name":"group0","non-member-readable":"false",
{"id":"8c0f3816-9e5e-4239-a842-79ecab53ca82","self-administered":"true",
"description":"the description","name":"group1","non-member-readable":"true"}
Fail 409 username is not a registered user

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.

Request

Required headers: none

Verb URL
DELETE groupmanagement/group/{groupid}

Response

Status Code Detail
OK 200  
Fail 409 username is not an administrator
Fail 409 Group does not exist
Fail 409 Forbidden to delete the "gs-public" group