Nothing Special   »   [go: up one dir, main page]

Skip to content

Users

Users

Query and manage users.

Only users fulfilling the conditions below will be present in the REST API.

  • User MUST have a confirmed email address.
  • User MUST be active.
  • User MUST have set the profile visibility to public.

Authentication required

Requests to search REST API endpoints require authentication. Results sets are limited to max 10 results per query (i.e. pagination is not supported).

Search users

Search for users

GET /api/users

Parameters

Name Type Location Description
q string query Search query used to filter results.
sort string query Sort search results. Customizable. Built-in options are "bestmatch", "username", "email", "domain", "newest", "oldest", "updated" (default: "bestmatch" or "newest").
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
accept string header - application/json

Sort options for users can be configured using the USERS_RESOURCES_SORT_OPTIONS config variable as described in the search customization section. Note that "bestmatch" is only available as a sort option on requests that provide a query string as a q parameter, in which case it is the default sort type. If no query string is provided in the request, the default sort type is "newest". In this case a "bestmatch" value is ignored and the default "newest" sort is used.

Query string syntax

The query string syntax is based on ElasticSearch's query string syntax.

The following search fields:

  • username
  • email
  • name or full_name or fullname
  • affiliation or affiliations

Request

GET /api/users?q=cern HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "hits": {
    "hits": [
      {
        "email": "jose.benito.gonzalez@cern.ch",
        "id": "4",
        "is_current_user": false,
        "links": {
          "avatar": "https://127.0.0.1:5000/api/users/4/avatar.svg",
          "self": "https://127.0.0.1:5000/api/users/4"
        },
        "profile": {
          "affiliations": "CERN",
          "full_name": "Jose Benito Gonzalez Lopez"
        },
        "username": "jbenito"
      },
      {
        "active": true,
        "confirmed": true,
        "created": "2022-05-23T12:03:48.466772+00:00",
        "email": "lars.holm.nielsen@cern.ch",
        "id": "3",
        "is_current_user": true,
        "links": {
          "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg",
          "self": "https://127.0.0.1:5000/api/users/3"
        },
        "preferences": {
          "email_visibility": "public",
          "visibility": "public"
        },
        "profile": {
          "affiliations": "CERN",
          "full_name": "Lars Holm Nielsen"
        },
        "revision_id": 5,
        "updated": "2022-05-23T12:04:16.204875+00:00",
        "username": "lnielsen"
      }
    ],
    "total": 2
  },
  "links": {
    "self": "https://127.0.0.1:5000/api/users"
  },
  "sortBy": "bestmatch"
}

Get a user

GET /api/users/{id}

Both authenticated and unauthenticated access is possible.

The following object-level fields are only accessible for the authenticated user themselves:

  • revision_id
  • created
  • updated
  • active
  • confirmed
  • preferences

The following fields are only accessible for if email visibility is set to public:

  • email

Parameters

Name Type Location Description
id string path The user identifier.
accept string header - application/json

Errors

  • 403: The user does not exist or the profile is not public.

Request

GET /api/users/{id} HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "3",
  "revision_id": 5,
  "created": "2022-05-23T12:03:48.466772+00:00",
  "updated": "2022-05-23T12:04:16.204875+00:00",
  "active": true,
  "confirmed": true,
  "is_current_user": true,
  "username": "lnielsen",
  "email": "lars.holm.nielsen@cern.ch",
  "profile": {
    "affiliations": "CERN",
    "full_name": "Lars Holm Nielsen"
  },
  "preferences": {
    "email_visibility": "public",
    "visibility": "public"
  },
  "links": {
    "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg",
    "self": "https://127.0.0.1:5000/api/users/3"
  }
}

Get avatar for user

GET /api/users/{id}/avatar.svg

Both authenticated and unauthenticated access is possible.

Parameters

Name Type Location Description
id string path The user identifier.

Errors

  • 403: The user does not exist or the profile is not public.

Request

GET /api/users/{id}/avatar.svg HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline; filename=avatar.svg
Content-Length: 351
Content-Type: image/svg+xml; charset=utf-8
ETag: "L#f06292"
...

 <svg width="256" height="256" xmlns="http://www.w3.org/2000/svg">
    <circle cx="125" cy="125" r="125" fill="#f06292" stroke="grey" />
    <text x="48%" y="53%" dominant-baseline="middle" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="125" fill="#f9f9f9" stroke="grey" stroke-width="2">
            L
    </text>
  </svg>