Mod-Users BL Documentation

Business Logic Users API

A front end for mod-users and mod-permissions

Endpoints

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

/bl-users

get

Description

Get a number of user (and possibly related) records based on criteria in the user and related modules

Query Parameters

include string

indicates which referenced fields should be populated (de-referenced) by the service

offset integer
Maximum: 2147483647

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

limit integer
Default: 10 Maximum: 2147483647

Limit the number of elements returned in the response

Example: 10
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

Responses

200 OK

Response Example (application/json)

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

403 Forbidden

Access denied

Response Example (text/plain)
Access denied

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/_self

get

Description

Get a user by self reference

Query Parameters

expandPermissions boolean

Whether or not to expand permissions listings

include string

indicates which referenced fields should be populated (de-referenced) by the service

Responses

200 OK

Response Example (application/json)

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

403 Forbidden

Access denied

Response Example (text/plain)
Access denied

404 Not Found

User not found

Response Example (text/plain)
User not found

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/by-id

/bl-users/by-id/{id}

URI Parameters

id string required

get

Description

Get a user by id

Query Parameters

include string

indicates which referenced fields should be populated (de-referenced) by the service

expandPermissions boolean

Whether or not to expand permissions listings

Responses

200 OK

Response Example (application/json)

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

403 Forbidden

Access denied

Response Example (text/plain)
Access denied

404 Not Found

User not found

Response Example (text/plain)
User not found

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/by-username

/bl-users/by-username/{username}

URI Parameters

username string required

get

Description

Get a user by username

Query Parameters

include string

indicates which referenced fields should be populated (de-referenced) by the service

expandPermissions boolean

Whether or not to expand permissions listings

Responses

200 OK

Response Example (application/json)

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

403 Forbidden

Access denied

Response Example (text/plain)
Access denied

404 Not Found

User not found

Response Example (text/plain)
User not found

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/forgotten

/bl-users/forgotten/password

post

Description

called when a user has forgotten a password

Request JSON Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  }
}

Request Example (application/json)

Responses

204 No Content

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/forgotten/username

post

Description

called when a user has forgotten a username

Request JSON Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  }
}

Request Example (application/json)

Responses

204 No Content

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/login

post

Description

Allow a new user to login and return an authtoken, along with a composite user record

Query Parameters

include string

indicates which referenced fields should be populated (de-referenced) by the service

expandPermissions boolean

Whether or not to expand permissions listings

Request JSON Schema

{
  "title": "Login Credentials Schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "userId": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  }
}

Request Example (application/json)

Responses

201 Created

Response Headers

x-okapi-token string
Response Example (application/json)

400 Bad Request

Bad request

Response Example (text/plain)
Bad request

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error

/bl-users/settings

/bl-users/settings/myprofile

/bl-users/settings/myprofile/password

post

Description

Allow change password for user

Request JSON Schema

{
  "title": "Update Credentials Schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "userId": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "newPassword" : {
      "type": "string"
    }
  }
}

Request Example (application/json)

Responses

204 No Content

Successful update

Response Example (text/plain)

400 Bad Request

Bad request

Response Example (application/json)

401 Unauthorized

Unauthorized

Response Example (text/plain)
Unauthorized

500 Internal Server Error

Internal server error

Response Example (text/plain)
Internal server error