User

• Overview
• Get a single user
• Get the authenticated user
• Partial update of the authenticated user
• List all users
• Create new user
• Update user
• Deactivates a user account

Overview

The API exposes a representation of OCL users. Many of the actions supported by the API, such as modifying a collection, require an authenticated user and the authentication information must be passed with the request.

Versioning of users

• Version history is not stored for users - edits are in-place and only "createdOn" and "updatedOn" are maintained

Considerations

• Support administrative access to edit users through POST /users/:user?
• Include OCL's internal UUID in the GET responses? If this isn't used anywhere, let's remove
• Which fields should be included in the GET /users response?
• Should all returned resources have the standard display, displayLocale, properties, and auditInfo fields like I was originally planning?
• Sharing of collections and sources is not here yet - previously these were modeled using "roles": { "uuid","display","name","description","privileges"}
• How to retire and/or delete users?
• Possible future functionality:
  • Optional gravatar image for the user

Get a single user

• Get the public version of a user

GET /users/:user

Response

• Status: 200 OK

{
    "type": "User",
    "uuid": "8d94f280-c2cc-11de-8d13-0010c6dffd0f",

    "username": "johndoe",
    "name": "John Doe",
    "company": "My Company",
    "location": "Kenya",
    "email": "johndoe@me.com",
    "preferredLocale": "en",

    "url": "/users/johndoe",
    "collections_url": "/users/johndoe/collections",
    "sources_url": "/users/johndoe/sources",
    "orgs_url": "/users/johndoe/orgs",

    "orgs": 3,
    "publicCollections": 3,
    "publicSources": 1,
    "starredCollections": 14,
    "starredConcepts": 9,
    "starredSources": 2,

    "createdOn": "2008-01-14T04:33:35Z",
    "updatedOn": "2008-02-18T09:10:16Z"
}

Get the authenticated user

• Get the non-public version of the authenticated user

GET /user

• Note that authentication information must be passed with the request. E.g. curl -u "username" "/user"

Response

• Status: 200 OK
• Currently this returns the same JSON response as GET /users/:user, but this will change as non-public functionality is added

Partial update of the authenticated user

• Use to update selected fields in the currently authenticated user - Note that there is no support for POST /users/:user (although possibly support this for administrative users?)

POST /user

• For the partial update, pass only the fields that will be updated
• Note that authentication information for the user to be updated must be passed with the request. E.g. curl -u "username" "/user"
• Input
  • name (optional) string - public name
  • email (optional) string - public email address
  • company (optional) string - public company name
  • location (optional) string - public location (e.g. Boston, MA, USA)
  • preferredLocale (optional) string - ordered, comma-separated list of preferred locales (e.g. "en", "es", "en,es")

{
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferredLocale": "en,sw"
}

Response

• Status: 200 OK
• Returns the full, non-public JSON representation of the updated user object, same as GET /user.

List all users

• List all users
• Returns the reference JSON representation only
• Default sort is "createdOn" ascending - meaning the order in which users were created (???)

GET /users

• Parameters
  • "q" (optional) - search criteria to filter users

Response

• Status: 200 OK

[
    {
        "username": "johndoe",
        "name": "John Doe",
        "url": "/users/johndoe"
    }
]

Create new user

• Create new user - requires administrative rights - standard users will do this through the web application and will use the web app's user account

POST /users

• Input
  • username (required) string - username; must be unique
  • name (required) string - public name
  • email (required) string - public email address
  • company (optional) string - public company name
  • location (optional) string - public location (e.g. Boston, MA, USA)
  • preferredLocale (optional) string - ordered, comma-separated list of preferred locales (e.g. "en", "es", "en,es")

{
    "username": "johnnydoe",
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferredLocale": "en,sw"
}

Response

• Status: 201 Created
• Location: http://api.openconceptlab.com/users/johnnydoe/

{
    "type": "User",

    "uuid": "8d94f280-c2cc-11de-8d13-0010c6dffd0f",
    "username": "johnnydoe",
    "name": "Johnny Doe",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "email": "jdoe@me.com",
    "preferredLocale": "en,sw",

    "url": "/users/johnnydoe/",
    "collections_url": "/users/johnnydoe/collections/",
    "sources_url": "/users/johnnydoe/sources/",
    "orgs_url": "/users/johnnydoe/orgs/",

    "orgs": 0,
    "publicCollections": 0,
    "publicSources": 0,
    "starredCollections": 0,
    "starredConcepts": 0,
    "starredSources": 0,

    "createdOn": "2008-01-14T04:33:35Z",
    "updatedOn": "2008-01-14T04:33:35Z",
}

Update user

• Update the specified user - this requires administrative rights

POST /users/:user

• For the partial update, pass only the fields that will be updated
• Note that authentication information for a user with administrative access must be passed with the request. E.g. curl -u "username" "/users/johndoe"
• Input
  • name (optional) string - public name
  • email (optional) string - public email address
  • company (optional) string - public company name
  • location (optional) string - public location (e.g. Boston, MA, USA)
  • preferredLocale (optional) string - ordered, comma-separated list of preferred locales (e.g. "en", "es", "en,es")

{
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferredLocale": "en,sw"
}

Response

• Status: 200 OK
• Returns the full, non-public JSON representation of the updated user object, same as GET /user.

Deactivates a user account

• A user account is deactivated through the web application and will use the web app's administrative user account
• This requires administrative rights

DELETE /users/:user

• Note that this only deactivates the account using an internal flag. This effectively hides the user account and any data or metadata it owns, but does not delete it from the system.
• Note that authentication information for a user with administrative access must be passed with the request. E.g. curl -u "username" "/users/johndoe"

Response

• Status: 204 No Content