Created
September 19, 2017 18:42
-
-
Save bsavage/ff1b2e5bb38224de8ed339e9bb7bdc29 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
swagger: '2.0' | |
info: | |
title: Grouper SCIM-like operations | |
version: "v2" | |
contact: | |
email: tier-api@internet2.edu | |
name: TIER API Working Group | |
url: 'https://spaces.internet2.edu/display/DSAWG' | |
description: "The TIER APIs helps education and research organizations with Identity and Access Management (IAM) challenges. This API definition represents the grouper custom Users and Gropus operations provided by UPenn leveraging SCIM resource libraries provided by Penn State." | |
termsOfService: 'http://www.internet2.edu/policies/intellectual-property-framework/' | |
schemes: | |
- https | |
host: grouperdemo.internet2.edu | |
basePath: /grouper-ws-scim_v2_3/v2 | |
securityDefinitions: | |
grouperAuth: | |
type: basic | |
description: HTTP Basic Authentication. | |
externalDocs: | |
url: 'https://spaces.internet2.edu/display/DSAWG/' | |
consumes: | |
- application/scim+json | |
produces: | |
- application/scim+json | |
tags: | |
- description: Users representation operations | |
name: Users | |
- description: Groups representation operations | |
name: Groups | |
- description: Membership representation operations | |
name: Memberships | |
paths: | |
'/Groups/{groupId}': | |
get: | |
summary: Get members of a specified group | |
description: Get members of a specified group (using path syntax). | |
(Using a gropuId such as cf0f06202d434a5ca844d8084ebcf2bc) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: groupId | |
description: Id of group | |
in: path | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/GroupObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
post: | |
summary: Create a group | |
description: Create a group | |
Notes - When creating a group | |
1) group name must have a colon (:) in it. | |
2) user must have sufficient privilegee | |
3) same group must not exist already | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: groupId | |
description: Id of group | |
in: path | |
type: string | |
required: true | |
- name: GroupJson | |
in: body | |
description: Group information to be posted | |
required: true | |
schema: | |
$ref: '#/definitions/GroupInput' | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/GroupObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Groups | |
put: | |
summary: Update a group | |
description: Update a group | |
Notes - When updating a group | |
1) group name must have a colon (:) in it. | |
2) user must have sufficient privilegee | |
3) same group must not exist already | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: groupId | |
description: Id of group | |
in: path | |
type: string | |
required: true | |
- name: GroupJson | |
in: body | |
description: Group information to be posted | |
required: true | |
schema: | |
$ref: '#/definitions/GroupInput' | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/GroupObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Groups | |
delete: | |
summary: Delete a group | |
description: Delete a group. | |
Notes - | |
a) caller must have sufficient privileges to delete a group. | |
b) alternate unique group id (such as systemName and idIndex can also be used as the groupId | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: groupId | |
description: Id of group | |
in: path | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/GroupObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Groups | |
'/Groups': | |
get: | |
summary: Gets groups using search filter | |
description: Search groups and return a matching list (using query syntax) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: filter | |
description: Filter for group search. Filter composition is a field (uuid, name, displayName, extension, displayExtension, idIndex, description), an operator (eq, co) and a double-quoted string value (e.g, uuid eq "cf0f06202d434a5ca844d8084ebcf2bc") | |
`Note these standards and exceptions | |
a) values associated with "eq" operator are case sensitive, | |
b) values associated with "co" operator are case insensitive, and | |
c) co (contains) operator cannot be specified for uuid, name or idIndex` | |
in: query | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/GroupObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Groups | |
'/Memberships/{membershipId}': | |
get: | |
summary: Get a membership | |
description: Get the specified membership (using path syntax) | |
Notes - when getting a membership | |
1) membership must exist already | |
2) caller must have sufficient privileges | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: membershipId | |
description: Id of membership | |
in: path | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/MembershipObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
tags: | |
- Memberships | |
put: | |
summary: Update a membership | |
description: Update a membership | |
Notes - When updating a membership | |
1) membership must exist already | |
2) caller must have sufficient privileges | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: membershipId | |
description: Id of membership | |
in: path | |
type: string | |
required: true | |
- name: MembershipJson | |
in: body | |
description: Membership information to be posted | |
required: true | |
schema: | |
$ref: '#/definitions/MembershipInput' | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/MembershipObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Memberships | |
delete: | |
summary: Delete a membership | |
description: Delete a membership. | |
Notes - when deleting a membership | |
1) membership must exist already | |
2) user must have sufficient privileges | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: membershipId | |
description: Id of membership | |
in: path | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/MembershipObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Memberships | |
'/Memberships': | |
get: | |
summary: Gets memberships using search filter | |
description: Search groups and return a matching list (using query syntax) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: filter | |
description: Filter for membership search. Filter composition is a field (groupId, groupName, groupIdIndex, subjectId, subjectIdentifier), an operator (eq, co) and a double-quoted string value (e.g, uuid eq "cf0f06202d434a5ca844d8084ebcf2bc") | |
*Note these standards and exceptions | |
a) values associated with "eq" operator are case sensitive, | |
b) values associated with "co" operator are case insensitive, and | |
c) co (contains) operator cannot be specified for uuid, name or idIndex | |
Finally, it is possible to use a compound search using eq with both groupId and subjectId.* | |
in: query | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/MembershipObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Memberships | |
post: | |
summary: Create a membership | |
description: Create a membership. | |
Notes - When updating a group | |
1) input must have owner and member properties | |
2) owner group must exist for provided owner group id | |
3) member you are trying to add in the group must not be in the group already | |
4) caller must have sufficient privileges | |
5) the groupId can be a uuid, a systemName (string), or ddIndex (a Long value) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: MembershipJson | |
in: body | |
description: Membership information to be posted. | |
Note these standards and exceptions | |
a) the owner object in the post can alternately be systemName (as in the example), idIndex (a Long value) and value (UUID of group) | |
required: true | |
schema: | |
$ref: '#/definitions/MembershipInput' | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/MembershipObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Memberships | |
'/Users/{userId}': | |
get: | |
summary: Get a user | |
description: Get the specified user (using path syntax) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: userId | |
description: Id of user | |
in: path | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/UserObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Users | |
'/Users': | |
get: | |
summary: Get user using search format | |
description: Search for a matching user (using query syntax) | |
security: | |
- grouperAuth: [] | |
parameters: | |
- name: filter | |
description: Filter for user search. Filter composition is a field (id or identifier), the eq operator, and a double-quoted string value container the unique user identifier (e.g., id eq "vsachdeva"). | |
in: query | |
type: string | |
required: true | |
responses: | |
'200': | |
description: The request has succeeded. | |
schema: | |
$ref: '#/definitions/UserObject' | |
'400': | |
description: Invalid request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'401': | |
description: Unauthorized request | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'403': | |
description: Forbidden | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'404': | |
description: Representation not found | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
'500': | |
description: Internal server error | |
schema: | |
$ref: '#/definitions/ErrorObject' | |
tags: | |
- Users | |
definitions: | |
GroupInput: | |
description: Body for group creation | |
type: object | |
properties: | |
displayName: | |
type: string | |
urn:grouper:params:scim:schemas:extension:TierGroupExtension: | |
type: object | |
properties: | |
systemName: | |
type: string | |
description: | |
type: string | |
required: | |
- systemName | |
- description | |
schemas: | |
type: array | |
items: | |
type: string | |
required: | |
- displayName | |
- urn:grouper:params:scim:schemas:extension:TierGroupExtension | |
- schemas | |
example: | |
displayName: Group display name | |
urn:grouper:params:scim:schemas:extension:TierGroupExtension: | |
description: Group description | |
systemName: test:groupTest1 | |
schemas: [ | |
"urn:ietf:params:scim:schemas:core:2.0:Group", | |
"urn:grouper:params:scim:schemas:extension:TierGroupExtension" | |
] | |
MembershipInput: | |
description: Body for membership creation | |
type: object | |
properties: | |
enabledTime: | |
type: string | |
disabledTime: | |
type: string | |
owner: | |
type: object | |
properties: | |
groupId: | |
type: string | |
required: | |
- groupId | |
member: | |
type: object | |
properties: | |
value: | |
type: string | |
required: | |
- value | |
schemas: | |
type: array | |
items: | |
type: string | |
required: | |
- owner | |
- member | |
- schemas | |
example: | |
enabledTime: '2016-01-23T04:56:22Z' | |
owner: | |
systemName: test:groupTest1 | |
member: | |
value: jstreeter@wisc.edu | |
schemas: | |
- urn:tier:params:scim:schemas:Membership | |
GroupObject: | |
description: Describes response for one group. | |
type: object | |
properties: | |
meta: | |
type: object | |
properties: | |
version: | |
type: string | |
required: | |
- version | |
id: | |
type: string | |
displayName: | |
type: string | |
members: | |
type: array | |
items: | |
type: object | |
properties: | |
value: | |
type: string | |
"ref": | |
type: string | |
type: | |
type: string | |
required: | |
- value | |
- "ref" | |
- type | |
schemas: | |
type: array | |
items: | |
type: string | |
urn:tier:params:scim:schemas:extension:TierMetaExtension: | |
type: object | |
properties: | |
resultCode: | |
type: string | |
responseDurationMillis: | |
type: integer | |
required: | |
- resultCode | |
- responseDurationMillis | |
urn:grouper:params:scim:schemas:extension:TierGroupExtension: | |
type: object | |
properties: | |
description: | |
type: string | |
idIndex: | |
type: integer | |
systemName: | |
type: string | |
required: | |
- description | |
- idIndex | |
- systemName | |
required: | |
- meta | |
- id | |
- displayName | |
- schemas | |
- urn:tier:params:scim:schemas:extension:TierMetaExtension | |
- urn:grouper:params:scim:schemas:extension:TierGroupExtension | |
MembershipObject: | |
description: Describes response for one membership. | |
type: object | |
properties: | |
meta: | |
type: object | |
properties: | |
version: | |
type: string | |
required: | |
- version | |
id: | |
type: string | |
enabledTime: | |
type: string | |
enabled: | |
type: boolean | |
membershipType: | |
type: string | |
owner: | |
type: object | |
properties: | |
value: | |
type: string | |
display: | |
type: string | |
systemName: | |
type: string | |
"ref": | |
type: string | |
required: | |
- value | |
- display | |
- systemName | |
- "ref" | |
member: | |
type: object | |
properties: | |
value: | |
type: string | |
display: | |
type: string | |
"ref": | |
type: string | |
schemas: | |
type: array | |
items: | |
type: string | |
required: | |
- meta | |
- id | |
- enabledTime | |
- enabled | |
- membershipType | |
- owner | |
- member | |
- schemas | |
UserObject: | |
description: Describes response for user. | |
type: object | |
properties: | |
meta: | |
type: object | |
properties: | |
version: | |
type: string | |
required: | |
- version | |
id: | |
type: string | |
active: | |
type: boolean | |
displayName: | |
type: string | |
schemas: | |
type: array | |
items: | |
type: string | |
urn:tier:params:scim:schemas:extension:TierMetaExtension: | |
type: object | |
properties: | |
resultCode: | |
type: string | |
responseDurationMillis: | |
type: integer | |
required: | |
- resultCode | |
- responseDurationMillis | |
required: | |
- meta | |
- id | |
- active | |
- displayName | |
- schemas | |
- urn:tier:params:scim:schemas:extension:TierMetaExtension | |
ErrorObject: | |
description: Describes error responses. | |
type: object | |
properties: | |
detail: | |
type: string | |
status: | |
type: string | |
schemas: | |
type: array | |
items: | |
type: string | |
required: | |
- detail | |
- status | |
- schemas |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment