voot2swagger2.yaml

swagger: '2.0'
info:
  # Based on http://openvoot.org/protocol/
  version: 2.0.0
  title: VOOT version 2
host: voot-provider.example.org
basePath: /v2
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  oauth:
    type: oauth2
    # Voot2 describes token but not flow to obtain token.
    # This flow definition described here as it validated with swager
    # and allows including oauth security constraint specified on each path.
    flow: implicit
    # This is fabricated url showing what swagger2/oauth2 requires for authorizationUrl
    authorizationUrl: 'https://voot-provider.example.org/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token'
    scopes:
    # Only one scope descripte in protocol document
      general: To read any and all group data provided by voot2 api.
security:
  - oauth:
      - general
paths:
  /groups:
    get:
      summary: Group information
      description: 'The groups endpoint returns lists of groups associated with the current authentication user (token) - active, expired and inactive. The response includes a unique id for each group and a display name.  An empty list is returned if there are no groups for the authenticated user.'
      parameters:
        - name: query
          in: query
          description: Match terms for start of display name.
          required: false
          type: string
      responses:
        '200':
          description: An array of group ids and their associated display names
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
      security:
        - oauth:
            - general
  '/groups/{groupid}':
    get:
      description: 'Details about a group that the authenticated user has access to.  The user may retrieve group information for groups even if the user is not a member (for example, a public group).'
      parameters:
        - name: groupid
          in: path
          description: Id of the group
          required: true
          type: string
      responses:
        '200':
          description: Details about the group associated with the specified id
          schema:
            $ref: '#/definitions/Group'
      security:
        - oauth:
            - general
  '/groups/{groupid}/members':
    get:
      description: 'Gets all **active** members of the group specified by groupid provided the authenticated user has access.  Expired of otherwise inative members will not be returned by default.  An empty list is returned if there are no members.'
      parameters:
        - name: groupid
          in: path
          description: Id of the group
          required: true
          type: string
        - name: showAll
          in: query
          description: Directs provider to list all members of group including expired and inactive user memberships.
          required: false
          type: boolean
      responses:
        '200':
          description: An array of members associated with the specified group id
          schema:
            type: array
            items:
              $ref: '#/definitions/Membership'
      security:
        - oauth:
            - general
  /grouptypes:
    get:
      summary: Group types
      description: The grouptypes endpoint returns a list of groups types. The response includes the unique type id and display name.  An empty list is returned if no group types are found.
      responses:
        '200':
          description: An array of group types ids and their associated display names.
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
      security:
        - oauth:
            - general
  /me/groups:
    get:
      summary: Group membership of current user
      description: 'This endpoint returns a list of **active** groups memberships of the current user. By defaul, expired or otherwise inactive groups are not returned.  The response includes membership information including roles.  An empty list is returned if there are no groups for the authenticated user.'
      parameters:
        - name: showAll
          in: query
          description: Directs provider to list all groups the current authenticated user is associated with including expired and inactive user memberships.
          required: false
          type: boolean
      responses:
        '200':
          description: An array of group ids and their associated display names
          schema:
            type: array
            items:
              $ref: '#/definitions/GroupMemberships'
      security:
        - oauth:
            - general
  '/me/groups/{groupid}':
    get:
      summary: Relationship of current user to group specified
      description: "This endpoint returns the authenticated user's relationship to the specified group (via groupid parameter).  The user's relationship and display name for that relationship are returned."
      parameters:
        - name: groupid
          in: path
          description: Id of the group
          required: true
          type: string
      responses:
        '200':
          description: "User's relationship to group and its associated display name."
          schema:
            type: array
            items:
              $ref: '#/definitions/Relationship'
      security:
        - oauth:
            - general
definitions:
  Group:
    type: object
    properties:
      id:
        description: Unique idenfier for the group
        type: string
      displayName:
        description: Literal name of group
        type: string
  Membership:
    type: object
    properties:
      name:
        description: Member name
        type: string
      email:
        description: Member email
        type: string
      profilePhotoURL:
        description: Full URL that resolved to member photo
        type: string
      membership:
        description: Type of membership
        type: array
        items:
          $ref: '#/definitions/MembershipType'
  MembershipType:
    type: string
    properties:
      basic:
        description: Category of basic membership
        type: string
  Relationship:
    properties:
      name:
        $ref: '#/definitions/MembershipType'
      displayName:
        description: Display name of member relationship
        type: string
  GroupMemberships:
    type: object
    properties:
      group:
        $ref: '#/definitions/Group'
      relationship:
        $ref: '#/definitions/Relationship'
      active:
        description: Active or inactive status
        type: string
      notBefore:
        description: 'Time constraint on membership in ISO 8601 combined data and time form (e.g., 2006-08-01T12:00:00Z)'
        type: string
      public:
        description: 'True if group is public, false otherwise'
        type: boolean
      sourceID:
        description: Source of group information
        type: string