---
swagger: '2.0'
info:
  version: 1.0.0
  title: Users and Groups
  description: Organisation of security users and groups
  contact:
    name: GeoServer
    email: 'geoserver-users@osgeo.org'
    url: 'https://geoserver.org/comm/'
host: localhost:8080
basePath: /geoserver/rest/security

paths:
  /usergroup/users/:
    get:
      operationId: usersDefaultGet
      tags:
       - "UserGroup"
      summary: Query all users
      description: Query all users in the default user/group service.
      produces:
        - application/xml
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Users"    
    post:
      operationId: usersDefaultPost
      tags:
       - "UserGroup"
      summary: Add a new user
      description: Add a new user to the default user/group service      
      parameters:
        - name: usersDefaultPostBody
          description: the new user's details
          in: body
          required: true
          schema:
            $ref: "#/definitions/User"    
      consumes: 
        - application/json
        - application/xml
      responses:
        201:
          description: Created
          headers:
            ID:
              description: ID of the newly created user 
              type: string             
  /usergroup/service/{serviceName}/users/:
    get:
      operationId: usersGet
      tags:
       - "UserGroup"
      summary: Query all users
      description: Query all users in a particular user/group service.
      produces:
        - application/xml
        - application/json        
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Users"   
    post:
      operationId: usersPost
      tags:
       - "UserGroup"
      summary: Add a new user
      description: Add a new user to a particular user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string          
        - name: usersPostBody
          description: the new user's details
          in: body
          required: true
          schema:
            $ref: "#/definitions/User" 
      responses:
        201:
          description: Created
          headers:
            ID:
              description: ID of the newly created user
              type: string
  /usergroup/user/{user}:
    post:
      operationId: userDefaultPost
      tags:
       - "UserGroup"
      summary: Modify a user
      description: Modify a user in the default user/group service, unspecified fields remain unchanged.
      consumes: 
        - application/json
        - application/xml
      parameters:  
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string          
        - name: userDefaultPostBody
          description: the new user's details
          in: body
          required: true
          schema:
            $ref: "#/definitions/User"
      responses:
        200:
          description: OK
    delete:
      operationId: userDefaultDelete
      tags:
       - "UserGroup"
      summary: Delete a user
      description: Delete a user in the default user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters: 
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
  /usergroup/service/{serviceName}/user/{user}:
    post:
      operationId: userPost
      tags:
       - "UserGroup"
      summary: Modify a user
      description: Modify a user in a particular user/group service, unspecified fields remain unchanged.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string    
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
        - name: userPostBody
          description: the new user's details
          in: body
          required: true
          schema:
            $ref: "#/definitions/User"
      responses:
        200:
          description: OK
    delete:
      operationId: userDelete
      tags:
       - "UserGroup"
      summary: Delete a user
      description: Delete a user in a particular user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string    
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
  /usergroup/group/{group}/users:
    get:
      operationId: groupDefaultUserGet
      tags:
       - "UserGroup"
      summary: Query all users for a group
      description: Query all users for a group in the default user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Users" 
  /usergroup/user/{user}/groups:
    get:
      operationId: userDefaultGroupGet
      tags:
       - "UserGroup"
      summary: Query all groups for a user
      description: Query all groups for a user in the default user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Groups"  
  /usergroup/user/{user}/group/{group}:
    post:
      operationId: userGroupDefaultPost
      tags:
       - "UserGroup"
      summary: Associate a user with a group
      description: Associate a user with a group in the default user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
    delete:
      operationId: userGroupDefaultDelete
      tags:
       - "UserGroup"
      summary: Unassociate a user from a group
      description: Unassociate a user from a group in the default user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
  /usergroup/service/{serviceName}/group/{group}/users:
    get:
      operationId: groupUserGet
      tags:
       - "UserGroup"
      summary: Query all users for a group
      description: Query all users for a group in a particular user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string    
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Users"
  /usergroup/service/{serviceName}/user/{user}/groups:
    get:
      operationId: userGroupGet
      tags:
       - "UserGroup"
      summary: Query all groups for a user
      description: Query all groups for a user in a particular user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string          
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Groups"  
  /usergroup/service/{serviceName}/user/{user}/group/{group}:
    post:
      operationId: userGroupPost
      tags:
       - "UserGroup"
      summary: Associate a user with a group
      description: Associate a user with a group in a particular user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string          
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
    delete:
      operationId: userGroupDelete
      tags:
       - "UserGroup"
      summary: Unassociate a user from a group
      description: Unassociate a user from a group in a particular user/group service.
      produces:
        - application/xml
        - application/json
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string          
        - name: user
          description: the name of the user
          in: path
          required: true
          type: string
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
  /usergroup/groups/:
    get:
      operationId: groupsDefaultGet
      tags:
       - "UserGroup"
      summary: Query all groups
      description: Query all groups in the default user/group service.
      produces:
        - application/xml
        - application/json
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Groups"
  /usergroup/group/{group}:
    post:
      operationId: groupDefaultPost
      tags:
       - "UserGroup"
      summary: Add a group
      description: Add a group in the default user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string          
      responses:
        200:
          description: OK
    delete:
      operationId: groupDefaultDelete
      tags:
       - "UserGroup"
      summary: Delete a group
      description: Delete a group in the default user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
  /usergroup/service/{serviceName}/groups/:
    get:
      operationId: groupsGet
      tags:
       - "UserGroup"
      summary: Query all groups
      description: Query all groups in a particular user/group service.
      produces:
        - application/xml
        - application/json        
      parameters:
        - name: serviceName
          description: the name of the group group service
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Groups"
  /usergroup/service/{serviceName}/group/{group}:
    post:
      operationId: groupPost
      tags:
       - "UserGroup"
      summary: Add a group
      description: Add a group in a particular user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string    
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
    delete:
      operationId: groupDelete
      tags:
       - "UserGroup"
      summary: Delete a group
      description: Delete a group in a particular user/group service.
      consumes: 
        - application/json
        - application/xml
      parameters:
        - name: serviceName
          description: the name of the user/group service
          in: path
          required: true
          type: string    
        - name: group
          description: the name of the group
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
           
definitions:
    Users:
       title: users
       xml: 
         name: users
       type: array
       items:
          $ref: "#/definitions/User"             
          
    User:
       title: user
       xml: 
         name: user
       type: object
       properties:
         userName: 
           type: string
         password: 
           type: string
         enabled: 
           type: boolean
           enum:
             - true
             - false
    Groups:
       title: groups
       xml: 
         name: groups
       type: array
       items:
          $ref: "#/definitions/Group"
    Group:
       title: group
       xml: 
         name: group
       type: string