tierBasicGroupsSwagger.yaml

swagger: '2.0'
schemes:
  - https
host: tier.api.edu
basePath: /tier/v2
info:
  contact:
    email: [email protected]
    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 only the first few group-related operations."
  termsOfService: 'http://www.internet2.edu/policies/intellectual-property-framework/'
  title: TIER Basic Group Operations
  version:  1.0.0
externalDocs:
  url: 'https://spaces.internet2.edu/display/DSAWG/'
consumes:
  - application/json
produces:
  - application/json
tags:
  - description: Users representation operations
    name: Users
  - description: Groups representation operations
    name: Groups
paths:
  '/Users/{userId}/Groups':
    get:
      summary: Get groups to which the specified user belongs
      description:
        Retrieve groups to which a user belongs.
      parameters:
        - name: userId
          description: "Id of user"
          in: path
          type: string
          required: true
        - name: startIndex
          description: "Starting index for results"
          in: query
          type: integer
          required: false
        - name: count
          description: "Maximum number of results requested"
          in: query
          type: integer
          required: false
      responses:
        '200':
          description: The request has succeeded
          schema:
            $ref: '#/definitions/UserGroupList'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized request
        '404':
          description: Representation not found
        '500':
          description: Internal server error
      tags:
        - Users
  '/Groups/{groupId}/Members':
    get:
      summary: Get members of a group.
      description: Get members for the group specified.
      parameters:
        - name: groupId
          description: Id of group
          in: path
          type: string
          required: true
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/definitions/MemberList'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized request
        '404':
          description: Representation not found
        '500':
          description: Internal server error
      tags:
        - Groups
  '/Groups/{groupId}/Members/{userId}':
    get:
      summary: Determine if user specified is in group specified.
      description: Check group for presence of member.
      parameters:
        - name: groupId
          description: Id of group
          in: path
          type: string
          required: true
        - name: userId
          description: Id of user
          in: path
          type: string
          required: true
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/definitions/MemberList'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized request
        '500':
          description: Internal server error
      tags:
        - Groups
definitions:
  UserGroupList:
    description:  | 
      Describes a group list response for a user.  Based upon spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+user+groups
    properties:
      schemas:
        description: List of applicable schemas
        type: array
        items:
            type: string
      totalResults:
        description: Total groups found for user
        type: integer
      itemsPerPage:
        description: Items per response/page
        type: integer
      startIndex:
        description: Index for this response set
        type: integer
      resources:
        type: array
        items:
          type: object
          properties:
            value:
              description: GroupId
              type: string
            systemName:
              description: Group name
              type: string
            display:
              description: Group display name
              type: string
  MemberList:
    description:  |
      Describes the members contains within a specified group.  Based upon spaces.internet2.edu/display/DSAWG/TIER+API+SCIM+group+members
    properties:
      schemas:
        description: List of applicable schemas
        type: array
        items:
            type: string
      totalResults:
        description: Total members found
        type: integer
      itemsPerPage:
        description: Items per response/page
        type: integer
      startIndex:
        description: Index for this response set
        type: integer
      resources:
        type: array
        items:
          type: object
          properties:
            value:
              description:  MemberId
              type: string
            userName:
              description: Member username
              type: string
            netId:
              description: Member netId
              type: string
            display:
              description: Member display name
              type: string