tierGroupsSwagger.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 help education and research organizations with Identity and Access Management (IAM) challenges."
  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: Operations on users belonging to an organization
    name: Users
  - description: Operations on groups belonging to an organization
    name: Groups
  - description: Operations on schemas
    name: Schemas
paths:
  /Groups/{userId}/Groups:
    get:
      summary: Get groups a user belongs to.
      description: Retrieve groups a user belongs to.
      parameters:
        - description: 'Id of user'
          in: userId
          type: string
      responses:
        '200':
          description: The request has succeeded
          schema:
            $ref: '#/definitions/GroupCollection'
        '400':
          description: Bad request
        '401':
          description: Unauthorized request
        '500':
          description: Internal server error
      tags:
        - Groups
  /Groups/{groupId}/Members/{userId}:
    get:
      summary: Query to determine if user specified is in group specified.
      description: Check group for presence of member.
      parameters:
        - description: 'Id of group'
          in: groupId
          type: string
        - description: 'Id of user'
          in: userId
          type: string
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/definitions/Member'
        '400':
          description: Bad request
        '401':
          description: Unauthorized request
        '500':
          description: Internal server error
      tags:
        - Groups
definitions:
  Group:
    description: Describes a group
    properties:
      id:
        description: "The group's id"
        type: string
      displayName:
        description: "The group's display name"
        type: string
      meta:
        $ref: '#/definitions/GroupMetadata'
        description: Group metadata
    required:
      - meta
      - id
      - displayName
  GroupMetadata:
    description: Group metadata
    properties:
      created:
        description: The date and time the group was created
        format: date-time
        type: string
      lastModified:
        description: The date and time the group was last modified
        format: date-time
        type: string
      version:
        description: The group version
        type: string
      location:
        description: The URL where the group can be accessed
        type: string
  GroupCollection:
    description: Class describing a collection of groups
    properties:
      resources:
        description: The list of groups
        items:
          $ref: '#/definitions/Group'
        type: array
  GroupDefinition:
    description: Describes a gropu
    properties:
      displayName:
        description: "The group's display name"
        type: string
      members:
        description: An array of members
        items:
          $ref: '#/definitions/Member'
        type: array
    required:
      - displayName
  ResourceSchema:
    description: Describes the attributes and metadata constituting a resource such as a user.
    properties:
      attributes:
        description: "The resource's attributes"
        items:
          $ref: '#/definitions/SchemaAttribute'
        type: array
      description:
        description: "The resource's description"
        type: string
      endpoint:
        description: "The resource's HTTP addressable endpoint relative to the base URL, e.g. /Users."
        type: string
      id:
        description: "The resource's id, e.g. urn:scim:schemas:core:1.0:User"
        type: string
      name:
        description: "The resource's name, e.g. \"User\""
        type: string
      schema:
        description: "The resource's associated schema, e.g. urn:scim:schemas:core:1.0"
        type: string
    required:
      - id
      - name
      - description
      - schema
      - endpoint
      - attributes
  SchemaAttribute:
    description: Describes a resource attribute
    properties:
      caseExact:
        description: Indicates whether the attribute is case sensitive
        type: boolean
      description:
        description: "The attribute's description"
        type: string
      multiValued:
        description: Indicates whether the attribute can have multiple values
        type: boolean
      name:
        description: "The attribute's name"
        type: string
      readOnly:
        description: Indicates whether the attribute is mutable
        type: boolean
      required:
        description: Indicates whether the attribute is required
        type: boolean
      schema:
        description: "The attribute's associated scheme, e.g. urn:scim:schemas:core:1.0"
        type: string
      subAttributes:
        description: "The attribute's potential sub-attributes"
        items:
          $ref: '#/definitions/SchemaSubAttribute'
        type: array
      type:
        description: "The attribute's data type, e.g. String"
        type: string
    required:
      - name
      - type
      - multiValued
      - description
      - schema
      - readOnly
      - required
      - caseExact
  SchemaSubAttribute:
    description: Describes the sub-attribute of a resource attribute
    properties:
      caseExact:
        description: Indicates whether the attribute is case sensitive
        type: boolean
      description:
        description: "The attribute's description"
        type: string
      name:
        description: "The attribute's name"
        type: string
      readOnly:
        description: Indicates whether the attribute is mutable
        type: boolean
      required:
        description: Indicates whether the attribute is required
        type: boolean
      type:
        description: "The attribute's data type, e.g. String"
        type: string
    required:
      - name
      - type
      - description
      - readOnly
      - required
      - caseExact
  Member:
    description: Describes a group member
    properties:
      value:
        description: "The user's unique id"
        type: string
      edu:internet2:tier:User:netId:
        description: "The user's netId"
        type: string
      userName:
        description: "The user's username"
        type: string
      displayName:
        description: "The user's display name"
        type: string
      ref:
        description "The uri associated with the user"
  UserCollection:
    description: Class describing a collection of users
    properties:
      resources:
        description: The list of users
        items:
          $ref: '#/definitions/User'
        type: array
      totalResults:
        description: The number of users in the collection
        format: int64
        type: integer
    required:
      - resources
      - totalResults
  UserDefinition:
    description: Describes a new user
    properties:
      displayName:
        description: "The user's display name"
        type: string
      locale:
        description: "The user's language settings"
        type: string
      name:
        description: "The user's full name"
        type: string
      password:
        description: "The user's password"
        type: string
      timezone:
        description: "The user's time zone"
        type: string
      userName:
        description: "The user's username, usually their email address"
        type: string
  UserMetadata:
    description: User metadata
    properties:
      created:
        description: The date and time the user was created
        format: date-time
        type: string
      location:
        description: The URL where the user can be accessed
        type: string
    required:
      - created
      - location