Skip to content
This repository was archived by the owner on Aug 11, 2021. It is now read-only.

users

Jump to bottom
Jonathan Payne edited this page Feb 16, 2015 · 31 revisions

Table of Contents

Overview

Users

Overview

The API exposes a representation of OCL users. Access to most resources via the API requires 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 the standard audit fields are maintained ("created_on", "created_by", "updated_on" and "updated_by")

Future Considerations

  • Want to support optional gravatar images for users in the future

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",
    "preferred_locale": "en",
    "website": "http://mydomain.me/",          # NOT CURRENTLY IMPLEMENTED

    "url": "https://api.openconceptlab.org/v1/users/johndoe/",
    "collections_url": "https://api.openconceptlab.org/v1/users/johndoe/collections/",
    "sources_url": "https://api.openconceptlab.org/v1/users/johndoe/sources/",
    "orgs_url": "https://api.openconceptlab.org/v1/users/johndoe/orgs/",

    "extras": null,

    "orgs": 3,
    "public_collections": 3,
    "public_sources": 1,
    "starred_collections": 14,        # NOT CURRENTLY IMPLEMENTED
    "starred_concepts": 9,            # NOT CURRENTLY IMPLEMENTED
    "starred_sources": 2,             # NOT CURRENTLY IMPLEMENTED
    "followers": 2,                   # NOT CURRENTLY IMPLEMENTED

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

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" "https://api.openconceptlab.org/v1/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 a user

  • Update selected fields of the currently authenticated user
POST /user/
  • [OCL Admin only] Update a user
POST /users/: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" "https://api.openconceptlab.org/v1/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)
    • preferred_locale (optional) string - ordered, comma-separated list of preferred locales (e.g. "en", "es", "en,es")
    • website (optional) string - fully-specified URL
    • extras (optional) json dictionary - additional metadata
{
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferred_locale": "en,sw",
    "website": "http://mydomain.me/",
    "extras": { "my-field": "my-value" }
}

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 "created_at" ascending - meaning the order in which users were created (???)
GET /users/
  • Parameters
    • q (optional) - search criteria to filter users (searches across "username", "full_name", "company", and "location")
    • sortAsc/sortDesc (optional) - sort on one of the following attributes: "username", "date_joined" (default), "num_stars"

Response

  • Status: 200 OK
[
    {
        "username": "johndoe",
        "name": "John Doe",
        "url": "https://api.openconceptlab.org/v1/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)
    • preferred_locale (optional) string - ordered, comma-separated list of preferred locales (e.g. "en", "es", "en,es")
    • website (optional) string - fully-specified URL
    • extras (optional) json dictionary - additional metadata
{
    "username": "johnnydoe",
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferred_locale": "en,sw",
    "website": "http://mydomain.me/",
    "extras": { "my-field": "my-value" }
}

Response

{
    "type": "User",

    "uuid": "8d94f280-c2cc-11de-8d13-0010c6dffd0f",
    "username": "johnnydoe",
    "name": "Johnny Doe",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "email": "jdoe@me.com",
    "preferred_locale": "en,sw",
    "website": "http://mydomain.me/",         # NOT CURRENTLY IMPLEMENTED

    "extras": { "my-field": "my-value" },

    "url": "https://api.openconceptlab.org/v1/users/johnnydoe/",
    "collections_url": "https://api.openconceptlab.org/v1/users/johnnydoe/collections/",
    "sources_url": "https://api.openconceptlab.org/v1/users/johnnydoe/sources/",
    "orgs_url": "https://api.openconceptlab.org/v1/users/johnnydoe/orgs/",

    "orgs": 0,
    "public_collections": 0,
    "public_sources": 0,
    "starred_collections": 0,         # NOT CURRENTLY IMPLEMENTED
    "starred_concepts": 0,            # NOT CURRENTLY IMPLEMENTED
    "starred_sources": 0,             # NOT CURRENTLY IMPLEMENTED
    "followers": 0,                   # NOT CURRENTLY IMPLEMENTED

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johnnydoe",
    "updated_on": "2008-01-14T04:33:35Z",
    "updated_by": "johnnydoe"
}
  • Status: 400 Bad Request - if the user already exists, or other errors. (Cannot distinguish between already exists active, or deactivated users?)

List organizations that user is a member of

  • List organizations for the currently authenticated user
GET /user/orgs/
  • List organizations for the specified user
GET /users/:user/orgs/
  • Parameters
    • "q" (optional) - search criteria

Response

  • Status: 200 OK
[
    {
        "id": "My-Organization",
        "name": "My Organization",
        "url": "https://api.openconceptlab.org/v1/orgs/My-Organization/"
    }
]

Deactivate a user account

  • A user account is deactivated through the web application and will use the web app's administrative user account. To reactivate a deactivated user, see below.
  • 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" "https://api.openconceptlab.org/v1/users/johndoe/"

Response

  • Status: 204 No Content - if the user is deactivated successfully.
  • Status: 404 Not Found - if the user specified does not exist, or is already deactivated.

Reactivate a deactivated user account

  • This too requires administrative rights.
  • User is reactivated, as are any sources and collections belonging to the user.
PUT /users/:user/reactivate/

Response

  • Status: 204 No Content

Retrieve auth token

  • This is intended to be called by the application user.
  • We assume that the end user has authenticated with the application with a username & password.
  • We also assume that there is a corresponding API user with the same username (mnemonic), and that the application user supplied a hashed password when it created this API user.
POST /users/login/
  • Input
    • username (required) string - username that exists both in the application and in the API
    • password (required) string - hashed version of the end user's application password

Response

  • Status: 200 OK
{ "token": "akEg4ybtattVqANXbQLlm2e67PmW1" }

Issues

  • These attributes are not yet implemented in the user details: website, starred_collections, starred_concepts, starred_sources, followers
  • Confirm the implementation of "sortAsc" and "sortDesc"

Overview

Resources

Import / Export

Troubleshooting & Operations

Other

Clone this wiki locally