|
The Identity Server provides REST services for
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.
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.
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.
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.
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"} |
Status | Status Code | Body |
OK | 200 | |
Fail | 409 |
username already exists, invalid username characters, etc. |
Finalizes a registration request. The uuid parameter comes from an email that was sent to the user.
A login is not required.
Required headers: none
Verb | URL | Body |
GET | usermanagement/register/pendingUuid/{uuid} | [none] |
Status | Status Code | Body |
See Other | 303 | Redirects to an identityServer message page containing a success or fail message. |
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.
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} |
Status | Status Code | Reason |
OK | 204 | |
Fail | 404 | No such user, etc. |
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.
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 |
Status | Status Code | Body |
OK | 200 | [Plain text, not JSON] The number of milliseconds remaining. |
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.
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 |
Status | Status Code | Body |
OK | 200 | [Plain text, not JSON] The username. |
Returns all GenomeSpace usernames. A login is required for security but does not affect the results.
Required headers: Accept: application/json
Verb | URL |
GET | selfmanagement/usernames |
Status | Status Code | Body |
OK | 200 | {"usernames":["bob","ted","alice","jane"]} |
Returns all GenomeSpace usernames matching the email provided. A login is required for security but does not affect the results.
Required headers: Accept: application/json
Verb | URL |
GET | selfmanagement/email/{email address} |
Status | Status Code | Body |
OK | 200 |
[ ] |
Returns the logged-in user's registration info.
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) |
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"} |
Allows a GenomeSpace user to change his/her password or email address. A user login is required.
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) |
Status | Status Code | Body |
OK | 200 | [No content] |
Allows a GenomeSpace user to delete his/her GenomeSpace account. A user login is required.
Required headers: none
Verb | URL | Username source |
DELETE | selfmanagement/user | gs-token cookie |
DELETE | selfmanagement/user/{username} | query parameter (must match login) |
Status | Status Code | Body |
OK | 201 | [No content] |
Get the user action log entries for the current user over a specified time period. Requires user be logged in.
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 |
Status | Status Code | Body |
OK | 200 |
|
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.
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.
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> |
Status | Status Code | Sample HTTP header attribute |
OK | 201 |
Location: https://identity.genomespace.org:8444/identityServer/ groupmanagement/group/108129df-aa59-4da0-ae6b-0e3c1323684c |
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.
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 |
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 |
Gets the one specified profile, or returns 404 if profile not found.
Required headers: Accept: application/json
Verb | URL |
GET | selfmanagement/profile/{profileId} |
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 |
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.
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"} |
Status | Status Code | Sample HTTP header attribute |
OK | 204 |
Required headers: none
Verb | URL |
DELETE | selfmanagement/profile/{profileId} |
Status | Status Code | Sample HTTP header attribute |
OK | 204 |
Returns all group names and their ids. A login is required for security but does not affect the results.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/groups |
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"}]} |
Returns the groupId of all groups whose membership includes the specified user. A login is required for security but does not affect the results.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/user/{username}/groupids |
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"]} |
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.
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"}]} |
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 |
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.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/group/{groupid} |
{groupid} is the UUID generated when the group was created.
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 |
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.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/user/{username}/group |
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 |
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.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/readable/group |
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 |
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.
Required headers: Accept: application/json
Verb | URL |
GET | groupmanagement/manageable/group |
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 |
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.
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"}]} |
Status | Code | Body |
OK | 200 | (none) |
Fail | 409 | Username is not an administrator |
Fail | 409 | Group does not exist |
Deletes the group. The logged-in user must be an administrator of the group.
Required headers: none
Verb | URL |
DELETE | groupmanagement/group/{groupid} |
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 |