openapi: 3.0.1
info:
  title: Common User Service
  description: This service provides the means to manage users across Kallidus products
  version: v1
servers:
  - url: 'https://gateway.kallidusapi.com/common-user'
paths:
  /ping:
    get:
      summary: Ping Service
      description: Ping 'Common User' service.
      operationId: get-ping
      responses:
        '200':
          description: Service is running
  '/users/{userId}':
    get:
      summary: Get User
      description: Get User by Id or username
      operationId: 5d666faa3437077439e05ef4
      parameters:
        - name: userId
          in: path
          description: 'identifier of the user, or username'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: the requested user is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUser'
        '400':
          description: an empty guid or blank username is supplied
        '401':
          description: the caller cannot be authenticated
        '404':
          description: the user cannot be found
    put:
      summary: Update User
      description: Update User
      operationId: 5d70e78d161de22c43b7f0d3
      parameters:
        - name: userId
          in: path
          description: unique identifer of user to update
          required: true
          schema:
            type: string
      requestBody:
        description: User
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutUser'
      responses:
        '200':
          description: the user is successfully updated and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUser'
        '400':
          description: the user passed in is missing or invalid
        '401':
          description: the caller cannot be authenticated
        '404':
          description: the user cannot be found
    delete:
      summary: Delete User
      description: Delete User
      operationId: 5d778e94f695adb3e23a4cbf
      parameters:
        - name: userId
          in: path
          description: unique identifer of user to update
          required: true
          schema:
            type: string
      responses:
        '204':
          description: the user is successfully deleted
        '400':
          description: an empty guid is supplied
        '401':
          description: the caller cannot be authenticated
        '404':
          description: the user cannot be found
  /users:
    post:
      summary: Create User
      description: Create new User
      operationId: 5d70e24542ecca0c023a07b6
      requestBody:
        description: User
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostUser'
      responses:
        '201':
          description: the user is successfully created and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUser'
        '400':
          description: the user passed in is missing or invalid
        '401':
          description: the caller cannot be authenticated
        '409':
          description: the user name passed in already exists
    get:
      summary: Get Users
      description: Get Users with optional OData $filter parameter
      operationId: 5d778f0d5554cd83f87472ec
      parameters:
        - name: $filter
          in: query
          description: 'OData filter (supports Email, ImportKey and UserFieldX)'
          schema:
            type: string
      responses:
        '200':
          description: a collection of users are returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsers'
        '401':
          description: the caller cannot be authenticated
components:
  schemas:
    GetUser:
      type: object
      properties:
        Id:
          type: string
          format: guid
        DateCreated:
          type: string
          format: date-time
        DateModified:
          type: string
          format: date-time
        FirstName:
          type: string
        LastName:
          type: string
        UserName:
          type: string
        FullName:
          type: string
        EmailAddress:
          type: string
        MobileNumber:
          type: string
        Culture:
          type: string
        ImportKey:
          type: string
        IsEnabled:
          type: boolean
        StartDate:
          type: string
          format: date-time
        LeaveDate:
          type: string
          format: date-time
        JobTitle:
          type: string
        CustomInformation:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
            description: An array of Key/Value pairs describing any custom information that has been saved for the User.
      example:
        Id: string
        DateCreated: '1900-01-01T00:00:00.0000000+00:00'
        DateModified: '1900-01-01T00:00:00.0000000+00:00'
        FirstName: string
        LastName: string
        UserName: string
        FullName: string
        EmailAddress: string
        MobileNumber: string
        Culture: string
        ImportKey: string
        IsEnabled: false
        StartDate: '1900-01-01T00:00:00.0000000+00:00'
        LeaveDate: '1900-01-01T00:00:00.0000000+00:00'
        LmsRole: string
        JobTitle: string
        CustomInformation:
          - Key: string
    PostUser:
      type: object
      properties:
        FirstName:
          type: string
        LastName:
          type: string
        UserName:
          type: string
        EmailAddress:
          type: string
        MobileNumber:
          type: string
        ImportKey:
          type: string
        IsEnabled:
          type: boolean
        StartDate:
          type: string
          format: date-time
        LeaveDate:
          type: string
          format: date-time
        JobTitle:
          type: string
        CustomInformation:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
            description: An array of Key/Value pairs describing any custom information that has been saved for the User.
      example:
        FirstName: John
        LastName: Smith
        UserName: johnsmith
        EmailAddress: johnsmith@example.com
        MobileNumber: 01234567890
        ImportKey: '999'
        IsEnabled: true
        StartDate: '2018-07-02T11:02:39.3170000+00:00'
        LeaveDate: '2019-01-28T16:29:19.9500000+00:00'
        JobTitle: Developer
        CustomInformation:
          - Field1: abc
    PutUser:
      type: object
      properties:
        DateCreated:
          type: string
          format: date-time
        DateModified:
          type: string
          format: date-time
        FirstName:
          type: string
        LastName:
          type: string
        UserName:
          type: string
        EmailAddress:
          type: string
        MobileNumber:
          type: string
        ImportKey:
          type: string
        IsEnabled:
          type: boolean
        StartDate:
          type: string
          format: date-time
        LeaveDate:
          type: string
          format: date-time
        JobTitle:
          type: string
        CustomInformation:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
            description: An array of Key/Value pairs describing any custom information that has been saved for the User.
      example:
        DateCreated: '2018-07-02T11:02:39.3170000+00:00'
        DateModified: '2019-05-02T19:46:51.5800000+00:00'
        FirstName: John
        LastName: Smith
        UserName: johnsmith
        EmailAddress: johnsmith@example.com
        MobileNumber: 01234567890
        ImportKey: '123'
        IsEnabled: true
        StartDate: '2018-07-02T11:02:39.3170000+00:00'
        LeaveDate: '2019-01-28T16:29:19.9500000+00:00'
        JobTitle: Tester
        CustomInformation:
          - Field1: xyz
    GetUsers:
      type: array
      items:
        $ref: '#/components/schemas/GetUser'
      example:
        - Id: string
          DateCreated: '1900-01-01T00:00:00.0000000+00:00'
          DateModified: '1900-01-01T00:00:00.0000000+00:00'
          FirstName: string
          LastName: string
          UserName: string
          FullName: string
          EmailAddress: string
          MobileNumber: string
          Culture: string
          ImportKey: string
          IsEnabled: false
          StartDate: '1900-01-01T00:00:00.0000000+00:00'
          LeaveDate: '1900-01-01T00:00:00.0000000+00:00'
          LmsRole: string
          JobTitle: string
          CustomInformation:
            - Key: string
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query
security:
  - apiKeyHeader: []
  - apiKeyQuery: []