openapi: 3.0.0
info:
  title: Period
  version: 1.0.0
  description: >
    A **Period** is the validity interval of a record: the dates between which
    the record is

    considered current. It is the mechanism behind historicization — when a
    record is historicized

    its period is closed, so the record disappears from normal queries while
    remaining readable in

    history.


    `start_date` defaults to 1970-01-01 (open on the left) and `end_date` to
    9999-12-31 (open on the

    right), so a record left with the default values is valid at any date.


    Use this API to:

    - Read the validity interval of a record (filter by `entity_id`)

    - Correct the dates of a period, for example to reopen a record closed by
    mistake
tags:
  - name: period
servers:
  - url: http://service.4hse.com/
security:
  - Oauth2: []
  - AccessToken: []
paths:
  /period/view/{id}:
    get:
      summary: view
      operationId: viewPeriod
      tags:
        - period
      description: |
        Retrieve the periods of the entity identified by the given ID.
      parameters:
        - name: id
          in: path
          description: The ID of the entity
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The periods for the entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewResponseBody"
              example:
                entity_type: ACTION
                entity_name: Base safety (4 hours)
                owned:
                  - period_id: example-period-id
                    data: null
                    start_date: 2017-01-01 00:00:00
                    end_date: 2019-09-26 00:00:00
                    entity_id: example-action-id
                    entity_name: Base safety (4 hours)
                    entity_type: ACTION
                child:
                  example-action-subscription-id:
                    - dep_id: example-action-id
                      dep_type: ACTION
                      start_date: 2017-01-01 00:00:00
                      end_date: 2019-09-26 00:00:00
                      entity_id: example-action-subscription-id
                      entity_name: Jon Snow on Base safety (4 hours)
                      entity_type: ACTION_SUBSCRIPTION
                      level: "0"
                parent:
                  example-office-id:
                    - dep_id: example-office-id
                      dep_type: OFFICE
                      dep_name: San Jose central office
                      start_date: 2017-01-01 00:00:00
                      end_date: 2019-09-26 00:00:00
                      entity_id: example-action-id
                      entity_type: ACTION
                      level: "0"
  /period/update/{id}:
    put:
      summary: update
      operationId: updatePeriod
      tags:
        - period
      description: |
        Update the periods of the entity identified by the given ID.
      parameters:
        - name: id
          in: path
          description: The ID of the entity
          required: true
          schema:
            type: string
      requestBody:
        description: The periods to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRequestBody"
            example:
              periods:
                - period_id: example-period-id
                  start_date: 2017-01-01 00:00:00
                  end_date: 2019-09-26 00:00:00
          application/xml:
            schema:
              $ref: "#/components/schemas/UpdateRequestBody"
      responses:
        "200":
          description: The updated action
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateResponseBody"
              example:
                done: "true"
            application/xml:
              schema:
                $ref: "#/components/schemas/UpdateResponseBody"
              example:
                done: "true"
components:
  schemas:
    UpdateResponseBody:
      type: object
      description: Update entity periods response body
      example: '{"done":"true"}'
    UpdateRequestBody:
      type: object
      description: Update entity periods request body
      properties:
        periods:
          type: array
          items:
            type: object
            description: a period to write
            properties:
              period_id:
                type: string
                example: example-period-id
                description: unique identifier for the period
              start_date:
                type: string
                example: 2017-01-01 00:00:00
                description: start period date (default -infinitive)
                default: 1970-01-01 00:00:00
              end_date:
                type: string
                example: 2019-09-26 00:00:00
                description: end period date (default +infinitive)
                default: 9999-12-31 23:59:59
    ViewResponseBody:
      type: object
      description: Current entity periods response
      properties:
        entity_type:
          type: string
          example: ACTION
          description: Current entity type
        entity_name:
          type: string
          example: Base safety (4 hours)
          description: Current entity label
        owned:
          type: array
          description: Owned entity periods
          items:
            type: object
            properties:
              period_id:
                type: string
                example: example-period-id
                description: unique identifier for the period
              data:
                type: object
                default: null
                description: additional data, unused
              start_date:
                type: string
                example: 2017-01-01 00:00:00
                description: start period date (default -infinitive)
                default: 1970-01-01 00:00:00
              end_date:
                type: string
                example: 2019-09-26 00:00:00
                description: end period date (default +infinitive)
                default: 9999-12-31 23:59:59
              entity_id:
                type: string
                example: example-action-id
                description: unique identifier for entity
              entity_name:
                type: string
                example: Base safety (4 hours)
                description: entity label
              entity_type:
                type: string
                example: ACTION
                description: entity type
        child:
          type: object
          description: The list of all child (direct and not-direct) periods indexed by
            child entity_id
          properties:
            example-action-subscription-id:
              description: child entity_id
              type: array
              items:
                type: object
                properties:
                  dep_id:
                    type: string
                    example: example-action-id
                    description: parent entity_id
                  dep_type:
                    type: string
                    example: ACTION
                    description: parent entity_type
                  start_date:
                    type: string
                    example: 2017-01-01 00:00:00
                    description: start period date (default -infinitive)
                    default: 1970-01-01 00:00:00
                  end_date:
                    type: string
                    example: 2019-09-26 00:00:00
                    description: end period date (default +infinitive)
                    default: 9999-12-31 23:59:59
                  entity_id:
                    type: string
                    example: example-action-subscription-id
                    description: unique identifier for entity
                  entity_name:
                    type: string
                    example: Jon Snow on Base safety (4 hours)
                    description: entity label
                  entity_type:
                    type: string
                    example: ACTION_SUBSCRIPTION
                    description: entity type
                  level:
                    type: string
                    example: "0"
                    description: nesting level
        parent:
          type: object
          description: The list of all parent (direct and not-direct) periods indexed by
            parent entity_id
          properties:
            example-office-id:
              description: parent entity_id
              type: array
              items:
                type: object
                properties:
                  dep_id:
                    type: string
                    example: example-office-id
                    description: unique identifier for parent entity
                  dep_type:
                    type: string
                    example: OFFICE
                    description: parent entity_type
                  dep_name:
                    type: string
                    example: San Jose central office
                    description: parent entity label
                  start_date:
                    type: string
                    example: 2017-01-01 00:00:00
                    description: start period date (default -infinitive)
                    default: 1970-01-01 00:00:00
                  end_date:
                    type: string
                    example: 2019-09-26 00:00:00
                    description: end period date (default +infinitive)
                    default: 9999-12-31 23:59:59
                  entity_id:
                    type: string
                    example: example-action-id
                    description: unique identifier for current entity
                  entity_type:
                    type: string
                    example: ACTION
                    description: current entity type
                  level:
                    type: string
                    example: "0"
                    description: nesting level
    securitySchemes:
      OAuth2:
        type: oauth2
        flows:
          password:
            tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
            scopes: {}
          refreshToken:
            tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
            scopes: {}
      AccessToken:
        type: apiKey
        in: query
        name: access-token
