Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
436 lines (432 sloc) 12.2 KB
#%RAML 1.0
title: Permissions
version: v1
baseUri: http://github.com/org/folio/mod-auth/permissions
documentation:
- title: mod-permissions API
content: This module is responsible for managing and retrieving permissions in the FOLIO system
types:
permission: !include permission.json
permissionNameObject: !include permissionNameObject.json
permissionListObject: !include permissionListObject.json
permissionUser: !include permissionUser.json
permissionUserListObject: !include permissionUserListObject.json
permissionNameListObject: !include permissionNameListObject.json
permissionUpload: !include permissionUpload.json
errors: !include raml-util/schemas/errors.schema
traits:
validate: !include raml-util/traits/validation.raml
pageable:
queryParameters:
length:
description: "The maximum number of results to return."
required: false
type: integer
example: 10
minimum: 1
default: 10
maximum: 2147483647
start:
description: "The starting index in a list of results (starts at one)."
required: false
type: integer
minimum: 1
default: 1
maximum: 2147483647
sortable:
queryParameters:
sortBy:
description: "A comma-separated list of fieldnames to sort by"
required: false
type: string
queryable:
queryParameters:
query:
description: "A query string to filter users based on matching criteria in fields."
required: false
type: string
byPermission:
queryParameters:
hasPermissions:
description: "A list of permissions that any returned users must possess."
required: false
type: string
byMember:
queryParameters:
memberOf:
description: "A list of permission names that any returned permission must be a sub-permission of."
required: false
type: string
byOwner:
queryParameters:
ownedBy:
description: "A list of user names that any returned permissions must belong to."
required: false
type: string
indexSelectable:
queryParameters:
indexField:
description: "Specify a field other than 'id' to look up the permission user by"
required: false
type: string
example: "userId"
/perms:
/users:
get:
description: Get a list of users
is: [
pageable,
sortable,
queryable,
byPermission
]
responses:
200:
body:
application/json:
type: permissionUserListObject
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
403:
description: "Access Denied"
body:
text/plain:
example: "Access Denied"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
post:
description: Add a new user
is: [validate]
body:
application/json:
type: permissionUser
responses:
201:
body:
application/json:
type: permissionUser
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/{id}:
get:
description: Get a permission user
is: [ indexSelectable ]
responses:
200:
body:
application/json:
type: permissionUser
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
403:
description: "Access Denied"
body:
text/plain:
example: "Access Denied"
404:
description: "User not found"
body:
text/plain:
example: "User does not exist"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
put:
description: Modify an existing user
is: [validate]
body:
application/json:
type: permissionUser
responses:
200:
body:
application/json:
type: permissionUser
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
404:
description: "User not found"
body:
text/plain:
example: "User not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
delete:
description: Remove a user
responses:
204:
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
404:
description: "User not found"
body:
text/plain:
example: "User not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/permissions:
get:
description: Get permissions that a user has
queryParameters:
expanded:
description: Recursively return all subpermissions
required: false
type: string
example: "true"
full:
description: Return full permission objects, as opposed to just permission names
required: false
type: string
example: "true"
is: [
indexSelectable
]
responses:
200:
description: "An object of returned permissions"
body:
application/json:
type: permissionNameListObject
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
403:
description: "Access Denied"
body:
text/plain:
example: "Access Denied"
404:
description: "User not found"
body:
text/plain:
example: "User not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
post:
description: Add a permission to a user
is: [validate, indexSelectable]
body:
application/json:
type: permissionNameObject
responses:
200:
description: "The added permission"
body:
application/json:
type: permissionNameObject
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/{permissionname}:
delete:
description: Remove a permission from a user
is: [ indexSelectable ]
responses:
204:
400:
description: "Bad request"
body:
text/plain:
404:
description: "Permission not found in user"
body:
text/plain:
example: "Permission not found in user"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/permissions:
get:
description: Get a list of existing permissions
queryParameters:
expandSubs:
description: Return one level of subpermissions as objects if true. If false or omitted, expanded will be considered.
required: false
type: string
example: "true"
expanded:
description: Recursively return all subpermissions as strings if true. Is only considered if expandSubs is false or omitted.
required: false
type: string
example: "true"
includeDummy:
description: "Return placeholder 'dummy' permissions"
required: false
type: string
example: "true"
is: [
pageable,
sortable,
queryable,
byMember,
byOwner
]
responses:
200:
body:
application/json:
type: permissionListObject
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
post:
description: Add a new permission
is: [validate]
body:
application/json:
type: permissionUpload
responses:
201:
body:
application/json:
type:
permissionUpload
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/{id}:
get:
description: Get an existing permission by id
responses:
200:
body:
application/json:
type: permission
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
404:
description: "Permission not found"
body:
text/plain:
example: "Permission not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
put:
description: Modify an existing permission
is: [validate]
body:
application/json:
type: permissionUpload
responses:
200:
body:
application/json:
type: permissionUpload
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
404:
description: "Permission not found"
body:
text/plain:
example: "Permission not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
delete:
description: Remove a permission
responses:
204:
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
404:
description: "Permission not found"
body:
text/plain:
example: "Permission not found"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"
/purge-deprecated:
post:
description: purge deprecated permissions
responses:
200:
description: "A list of permission names purged"
body:
application/json:
type: permissionNameListObject
400:
description: "Bad request"
body:
text/plain:
example: "Bad request"
500:
description: "Internal server error"
body:
text/plain:
example: "Internal server error"