http://github.com/org/folio/mod-users
This documents the API calls that can be made to query and manage users of the system
Collection of user items.
Return a list of users
GET /usersJSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}]
Example:
active=true sortBy username
Order by field: field A, field B
Order
Skip over a number of elements by specifying an offset value for the query
Example:
0Limit the number of elements returned in the response
Example:
10facets 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
Requested language. Optional. [lang=en]
Returns a list of user items
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
}
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.
Media type: text/plain
Type: any
Example:
unable to list users -- malformed parameter 'query', syntax error at column 6Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list users -- unauthorizedInternal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorCreate a user
POST /usersRequested language. Optional. [lang=en]
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"
}
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created user item
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"
}
}
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.
Media type: text/plain
Type: any
Example:
"unable to add user -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create users -- unauthorizedValidation errors
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"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorGet a single user
GET /users/{userId}Requested language. Optional. [lang=en]
Returns item with a given ID
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"
}
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"user not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorDelete user item with given {userId}
DELETE /users/{userId}Requested language. Optional. [lang=en]
Item deleted successfully
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.
Media type: text/plain
Type: any
Example:
"unable to delete user -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"user not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorUpdate user item with given {userId}
PUT /users/{userId}Requested language. Optional. [lang=en]
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"
}
}
Item successfully updated
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.
Media type: text/plain
Type: any
Example:
"unable to update user -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"user not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator