Users (v1)

http://github.com/org/folio/mod-users

Table of contents

mod-users API

This documents the API calls that can be made to query and manage users of the system

/users

Collection of user items.

GET /users

Return a list of users

GET /users
Query Parameters
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode

active=true sortBy username
  • orderBy: (string)

    Order by field: field A, field B

  • order: (one of desc, asc - default: desc)

    Order

  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • facets: (array of string)

    facets to return in the collection result set, can be suffixed by a count of facet values to return, for example, patronGroup:10 default to top 5 facet values

  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of user items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of users",
  "properties": {
    "users": {
      "description": "List of userdata items",
      "type": "array",
      "id": "usersData",
      "items": {
        "type": "object",
        "$ref": "userdata.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    },
    "resultInfo": {
      "$ref": "raml-util/schemas/resultInfo.schema",
      "readonly": true
    }
  },
  "required": [
    "users",
    "totalRecords"
  ]
}

Example:

{
  "users": [
    {
      "username": "jhandey",
      "id": "7261ecaae3a74dc68b468e12a70b1aec",
      "active": true,
      "patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
      "meta": {
        "creation_date": "2016-11-05T0723",
        "last_login_date": ""
      },
      "personal": {
        "lastName": "Handey",
        "firstName": "Jack",
        "middleName": "Michael",
        "dateOfBirth": "1965-07-08T00:00:01Z",
        "phone": "+1 (212) 567-8912",
        "mobilePhone": "+1 (212) 678-9123",
        "email": "jhandey@biglibrary.org"
      }
    }
  ],
  "totalRecords": 1
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list users -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list users -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /users

Create a user

POST /users
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description" : "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "An ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if a user can log in, take out loans, etc.",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to",
      "type": "string"
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description" : "Deprecated",
      "type": "array",
      "items": {
      "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "username": "jhandey",
  "id": "7261ecaae3a74dc68b468e12a70b1aec",
  "active": true,
  "type": "patron",
  "patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
  "meta": {
    "creation_date": "2016-11-05T0723",
    "last_login_date": ""
  },
  "personal": {
    "lastName": "Handey",
    "firstName": "Jack",
    "email": "jhandey@biglibrary.org",
    "phone": "2125551212"
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created user item

Body

Media type: application/json

Type: any

Example:

{
  "username": "jhandey",
  "id": "7261ecaae3a74dc68b468e12a70b1aec",
  "active": true,
  "type": "patron",
  "patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
  "meta": {
    "creation_date": "2016-11-05T0723",
    "last_login_date": ""
  },
  "personal": {
    "lastName": "Handey",
    "firstName": "Jack",
    "email": "jhandey@biglibrary.org",
    "phone": "2125551212"
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add user -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create users -- unauthorized

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /users/{userId}

Get a single user

GET /users/{userId}
URI Parameters
  • userId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description" : "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "An ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if a user can log in, take out loans, etc.",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to",
      "type": "string"
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description" : "Deprecated",
      "type": "array",
      "items": {
      "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "username": "jhandey",
  "id": "7261ecaae3a74dc68b468e12a70b1aec",
  "active": true,
  "type": "patron",
  "patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
  "meta": {
    "creation_date": "2016-11-05T0723",
    "last_login_date": ""
  },
  "personal": {
    "lastName": "Handey",
    "firstName": "Jack",
    "email": "jhandey@biglibrary.org",
    "phone": "2125551212"
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"user not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /users/{userId}

Delete user item with given {userId}

DELETE /users/{userId}
URI Parameters
  • userId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete user -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"user not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /users/{userId}

Update user item with given {userId}

PUT /users/{userId}
URI Parameters
  • userId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description" : "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "An ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if a user can log in, take out loans, etc.",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to",
      "type": "string"
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description" : "Deprecated",
      "type": "array",
      "items": {
      "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "username": "jhandey",
  "id": "7261ecaae3a74dc68b468e12a70b1aec",
  "active": true,
  "type": "patron",
  "patronGroup": "4bb563d9-3f9d-4e1e-8d1d-04e75666d68f",
  "meta": {
    "creation_date": "2016-11-05T0723",
    "last_login_date": ""
  },
  "personal": {
    "lastName": "Handey",
    "firstName": "Jack",
    "email": "jhandey@biglibrary.org",
    "phone": "2125551212"
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update user -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"user not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator