openapi: 3.0.1
info:
  title: HCX User Registry APIs
  description: >-
    While the HCX exchange protocol by itself may not need to focus on the human user (as the exchange is between systems), operational management of the exchange infrastructure may require administrative infrastructure that may necessitate a registry for operational users from organizations running HCX as well as participating organizations.
  version: 1.0.0
tags:
  - name: Registry APIs
    description: HCX User Registry APIs
paths:
  /user/create:
    post:
      tags:
        - Registry APIs
      description: This API is to create a user in the registry. API generates a unique user id  and returns the id in the response on successfull creation of user.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Unix timestamp when the request is sent
                    example: "1629057611000"
                  user_id:
                    type: string
                    description: Machine generated/readable unique identifier of the user on the HCX instance.
                    example: "user01@HCX01"


        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/read/{user_id}:
    get:
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
          description: Unique identifier of the user/scheme on the HCX instance
      tags:
        - Registry APIs
      description: This API is to retrieve details of a single user from the registry, using their user id .
      security:
        - bearer_auth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UserReadResponse'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/search:
    post:
      tags:
        - Registry APIs
      description: |
        This API is to search for users in the registry. API returns list of users matching the input criteria.

        Search filter supports all the fields. If multiple filter conditions are provided, they are processed by applying AND operation.

        **Limit** and **Offset** are optional fields. The limit option allows you to limit the number of rows should be returned in the response, while offset allows you to omit a specified number of rows before the beginning of the result set.


        Following are the operations supported by search filter:

        * contains("contains")

        * eq("=")

        * neq("!=")

        * between("range")

        * or("or")

        * startsWith("startsWith")

        * endsWith("endsWith")

        * notContains("notContains")

        * notStartsWith("notStartsWith")

        * notEndsWith("notEndsWith")

        * queryString("queryString")

        * gt(">")

        * lt("<")

        * gte(">=")

        * lte("<=")


        Following are few example of search filter usage:

        1. Filters to fetch the list of users with user_id **user01@hcx** Search response will return the user details.

        ```
        {
          "filters": {
            "user_id": { "eq": "user01" }
          }
        }
        ```

        2. Filters to fetch the list of users with user name containing **user01**.
        ```
        {
          "filters": {
            "user_name": { "contains": "user01" }
          }
        }
        ```

        3. Filters with nested fields, the below filter will return list of users with the given role .
        ```
        {
          "filters": {
            "tenant_roles.roles": { "eq": "admin" }
          }
        }
        ```


      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/UserSearchRequest'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ResponseEnvelope'
                  - type: object
                    required:
                      - users
                    properties:
                      users:
                        type: array
                        description: List of users matching with the input search criteria
                        items:
                          $ref: '#/components/schemas/UserReadResponse'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/update:
    post:
      tags:
        - Registry APIs
      description: This API is to update a user's information in the registry. user_id must be mandatorily provided in the request.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Unix timestamp when the request is sent
                    example: "1629057611000"
                  user_id:
                    type: string
                    description: Machine generated/readable unique identifier of the user on the HCX instance.
                    example: "user01@HCX01"

        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/delete:
    post:
      tags:
        - Registry APIs
      description: This API is to delete a user from the registry. API only does a soft delete of the user.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - user_id
                  properties:
                    user_id:
                      type: string
                      description: Unique identifier of the user on the HCX instance
                      example: "user01@HCX01"

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Unix timestamp when the request is sent
                    example: "1629057611000"
                  user_id:
                    type: string
                    description: Machine generated/readable unique identifier of the user on the HCX instance.
                    example: "user01@HCX01"
                  status:
                    type: string
                    description: status of the user in the registry
                    example: "Inactive"

        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /participant/user/add:
    post:
      tags:
        - Registry APIs
      description: This API is to add users to a participant.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - participant_code
                    - users
                  properties:
                    participant_code:
                      type: string
                      description: Unique identifier of the participant on the HCX instance
                      example: "participant01@HCX01"
                    users:
                      type: array
                      items:
                        type: object
                      description: List of the users to be added to a participant.
                      example: [{"user_id": "user01", "role": "viewer"},{"user_id": "user02", "role": "config-manager"}]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Unix timestamp when the request is sent
                    example: "1629057611000"
                  status:
                    type: string
                    description: Status of the API.
                    example: "SUCCESS"
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /participant/user/remove:
    post:
      tags:
        - Registry APIs
      description: This API is to remove users from a participant.
      security:
        - bearer_auth: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - participant_code
                    - users
                  properties:
                    participant_code:
                      type: string
                      description: Unique identifier of the participant on the HCX instance
                      example: "participant01@HCX01"
                    users:
                      type: array
                      items:
                        type: object
                      description: List of users to be removed from a participant.
                      example: [“user01”, “user02”]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    description: Unix timestamp when the request is sent
                    example: "1629057611000"
                  status:
                    type: string
                    description: Status of the API.
                    example: "SUCCESS"
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Downstream systems down/unhandled exceptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:

    UserCreateRequest:
      required:
        - user_name
        - created_by
      type: object
      properties:
        user_name:
          type: string
          description: Human readable user name
          example: User 01
        pin:
          type: string
          description: Identification pin if needed to be set
        mobile:
          type: string
          description: Mobile number of the user
          example: 8522812345
        email:
          type: string
          format: email
          description: Email Id of the user
          example: user01@domain_name.com
        linked_user_id:
          type: string
          description: User ID in the source system
        tenant_roles:
          type: array
          items:
            type: object
          description: Base tenant of the admin user
          example: [{"participant_code":"pcpt@hcx","role":"admin"}]  
        created_by:
          description: participant_code or user_id  of the created_by user
          type: string
          example: Participant code / user Id



    UserSearchRequest:
      type: object
      additionalProperties: false
      properties:
        filters:
          type: object
          description: Filter conditions should be provider in filters.
          example: {"user_id": { "eq": "user01@HCX01" } }
        limit:
          type: number
          description: Size of the search result should return in the response.
          example: 10
        offset:
          type: number
          description: Offset is used to omit a specified number of rows before the beginning of the result set.
          example: 0

    UserUpdateRequest:
      type: object
      required:
        - user_id
      additionalProperties: false
      properties:
        user_id:
          type: string
          description: Unique identifier of the user/scheme on the HCX instance
          example: "user01@HCX01"
        user_name:
          type: string
          description: Human readable name for the user
          example: "user01"
        pin:
          type: string
          description: Identification pin if needed to be set
        mobile:
          type: string
          description: Mobile number of the user
          example: 8522812345
        email:
          type: string
          format: email
          description: Email Id of the user
          example: user01@domain_name.com
        linked_user_id:
          type: string
          description: User ID in the source system
        created_by:
          description: participant_code or user id  of the created user
          type: string
          example: Participant code / user Id


    UserReadResponse:
      type: object
      required:
        - user_id
      additionalProperties: false
      properties:
        user_id:
          type: string
          description: Unique identifier of the user/scheme on the HCX instance
          example: "user01@HCX01"
        user_name:
          type: string
          description: Human readable name for the user
        pin:
          type: string
          description: Identification pin if needed to be set
        mobile:
          type: string
          description: Mobile number of the user
          example: 8522812345
        email:
          type: string
          format: email
          description: Email Id of the user
          example: user01@domain_name.com
        linked_user_id:
          type: string
          description: User ID in the source system
        tenant_roles:
          type: array
          items:
            type: object
          description: Base tenant of the admin user
          example: [{"participant_code":"pcpt@hcx","role":"admin"}]
        created_by:
          description: participant_code or user id  of the created user
          type: string
          example: Participant code / user Id

    ResponseEnvelope:
      required:
        - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: Unix timestamp when the request is sent
          example: "1629057611000"

    ErrorResponse:
      required:
        - error
        - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: Unix timestamp when the response is sent.
          example: "1629057611000"

        error:
          $ref: '#/components/schemas/Error'
      description: This is a response to the ClaimForm API call
    Error:
      type: object
      properties:
        code:
          type: string
          description: error code from the system - expected to be namespaced for better readability
        message:
          type: string
          description: Short description of the error
        trace:
          type: string
          description: Long description supporting the Code

  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT