openapi: 3.2.0
info:
  version: 1.0.0
  title: High-Level Design FTTx Retrieve job result API
  description: "The High-Level Design FTTx API supports Fiber to the Home (FTTH) engineering jobs. It allows you to calculate the required work and cost for Fiber rollout in a provided region.\n\nRun the endpoints in this order:\n\n1. **POST /startJobS3** to retrieve a signed URL for Amazon S3 bucket. Send this URL using the following endpoint.\n2. **PUT /s3url_uploads/{jsonFileNameAndExtension}** to upload the job.\n3. **GET /jobStatus/{jobId}** to retrieve the status of the job.\n4. **GET / jobResultS3/{jobId}** to retrieve a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket. Send this URL using the following endpoint.\n5. **GET /Output/{jsonFileNameAndExtension}** to retrieve the results of the engineering job.\n\n ### Key highlights\n\n - **Security:** HTTPS, OAuth, Rate limit\n - **Versioning:** Supports version-less API, version tight. If no version\n is provided (in header) it defaults to latest version. \n\n  [Source view](https://app.swaggerhub.com/apis/kpn/high-level_design_ftth)<br/>\n  [Documentation view](https://app.swaggerhub.com/apis-docs/kpn/high-level_design_ftth)\n  \n  ---\n  \n  [KPN Developer](https://developer.kpn.com/)<br/>\n  [Getting Started](https://developer.kpn.com/getting-started)\n  \n"
servers:
- url: https://api-prd.kpn.com/network/kpn/ftth-engineering/
  variables: {}
security:
- oauth2: []
tags:
- name: Retrieve job result
paths:
  /jobStatus/{jobId}:
    get:
      tags:
      - Retrieve job result
      summary: Returns the current status of the calculation job identified by jobId
      description: This method is called by the HLD front-end to get the current status of a job
      parameters:
      - in: path
        name: jobId
        required: true
        schema:
          $ref: '#/components/schemas/jsonFileNameSchema'
      responses:
        200:
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobStatus'
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          $ref: '#/components/responses/forbidden'
        404:
          $ref: '#/components/responses/not_found'
        429:
          $ref: '#/components/responses/too_many'
        500:
          $ref: '#/components/responses/server_error'
        502:
          $ref: '#/components/responses/gateway_error'
        503:
          $ref: '#/components/responses/service_unavailable'
  /jobResultS3/{jobId}:
    get:
      tags:
      - Retrieve job result
      summary: Returns a signed URL where the results of an engineering job can be retrieved.
      description: When an engineering job is finished. This endpoint should be called first to retrieve a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket where the results are stored. More details on how to use this URL to retrieve the results are specified in the /Output endpoint.
      parameters:
      - in: path
        name: jobId
        required: true
        schema:
          $ref: '#/components/schemas/jsonFileNameSchema'
      responses:
        200:
          description: 'The expected response is a signed URL for the Amazon Simple Storage Service (Amazon S3) bucket.</br> This signed URL is then to be used to retreieve the engineering job results, see **/Output/{jsonFileNameAndExtension}**.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/signedOutputUrl'
        400:
          $ref: '#/components/responses/bad_request'
        401:
          $ref: '#/components/responses/unauthorized'
        403:
          $ref: '#/components/responses/forbidden'
        404:
          $ref: '#/components/responses/not_found'
        429:
          $ref: '#/components/responses/too_many'
        500:
          $ref: '#/components/responses/server_error'
        502:
          $ref: '#/components/responses/gateway_error'
        503:
          $ref: '#/components/responses/service_unavailable'
  /Output/{jsonFileNameAndExtension}:
    get:
      tags:
      - Retrieve job result
      summary: Retrieve the results of an engineering job.
      description: Retrieves the results of the engineering job. Use the signed URL received from /jobResultS3/{jobId} for this.
      servers:
      - url: https://ftth-engineering-prod.s3.amazonaws.com
        description: This API request is done towards an Amazon Simple Storage Service (Amazon S3) bucket instead of the API store server.
      parameters:
      - in: path
        name: jsonFileNameAndExtension
        required: true
        description: 'The **jobId** of the engineering job you defined in **/startJobS3** or **/jobResultS3** with added .json extension.  </br>

          Pattern: `^.+\.(json)$` </br>

          Example: `FTTx_AdamNorth_Input_Dec2020.json`

          '
        schema:
          $ref: '#/components/schemas/jsonFileNameAndExtensionSchema'
      - in: query
        name: X-Amz-Algorithm
        required: true
        description: 'Identifies the version of AWS Signature and the algorithm used to calculate the signature. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**. </br> Example: `AWS4-HMAC-SHA256`'
        schema:
          $ref: '#/components/schemas/amzAlgorithm'
      - in: query
        name: X-Amz-Credential
        required: true
        description: 'This parameter provides scope (AWS region and service) for which the signature is valid. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**. </br> Example: `AAAAAA%2F20201201%2Feu-west-1%2Fs3%2Faws4_request`'
        schema:
          $ref: '#/components/schemas/amzCredential'
      - in: query
        name: X-Amz-Date
        required: true
        description: "The date when the signedUrl was generated. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**.     </br>\n    Example: `20201201T120000Z`\n"
        schema:
          $ref: '#/components/schemas/amzDate'
      - in: query
        name: X-Amz-Expires
        required: true
        description: "Provides the time period, in seconds, for which the generated presigned URL is valid. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**. </br>\n    Example: `3600`\n"
        schema:
          $ref: '#/components/schemas/amzExpires'
      - in: query
        name: X-Amz-SignedHeaders
        required: true
        description: "Lists the headers used to calculate the signature. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS**. </br>\n    Example: `host`\n"
        schema:
          $ref: '#/components/schemas/amzSignedHeaders'
      - in: query
        name: X-Amz-Security-Token
        required: true
        description: 'Additional credential parameter. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**. </br>

          Example: `AAAAAAAAAAluX2VjEA0aCWV1LXdlc3QtMSJIMEYCIQDKnFBi14jhVzfJHKod%2FCpwTIFkAj3kttgcdNRSngk49gIhAK6DboCvbtAmjlWDG5pBgzaFV1lXC0yFZWelULkpV%2FNVKuUBCNb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNjUyNDM0MTA2NTI4Igwfybzhyrjg3aq7hbMquQHE00Xe9PiL%2BS%2BSlhrzrpOKg2y%2F5qfjbR2BrGcPpxta3EiBwUpvmXR%2F%2BqkQBG7BuJifYKaDkdnOS%2B3OzxkV2WRHnKnlNwann1vCLTS9AWGdNRFLE72iJ2s%2BT3lwQp%2BR6bGMjcfqEDm84MR3gINTpSp84y9bt9hoxtxfXzF8SfGv5LVoN45K8Rf%2B%2BqF7%2BwF03JWV50Klauq4hneHRiyWsUgQY6pFMN14xj83Jn5fxKJi0L7qh%2BWBfMnDCTCW1%2Fv%2FBTrfAbwZuNzIkBmhmHsmDO9hS2dLEfqpH9GpPUl8YLY3vfjATqpjnz241WrrBdyTawUFbiTEbcKx05dUwbkUdLRP2i9CZVLAl%2Bqk0J6VYmIEhhU2RS54oHCZzinEVzsdo%2BS5eXRQ9BiAD8OCH2gP3a7bXDx9HOBxSdbGMv5mXMeP1wsdjC7e%2FkVsQlEtBTNgc62EiloUbQlPiQyb1OQEMMGZd%2BV5N%2FxdNq%2For1UraAbvxAAzGHUqQff4rmZCEDbO5uv2kwWDR1boarpQeEG8Q3j%2BxSNde%2FG%2BUjg425uIAAAAAAAAAA`

          '
        schema:
          $ref: '#/components/schemas/amzSecurityToken'
      - in: query
        name: X-Amz-Signature
        required: true
        description: "The signature to authenticate your request. Use the value provided as part of the signed URL response of **/startJobS3** or **/jobResultS3**.\n  </br>\nExample: `aaaaaaaaaa09c013193ffd301019b60308a092c972b22fdfcb8424bbbbbbbbbb`\n"
        schema:
          $ref: '#/components/schemas/amzSignature'
      responses:
        200:
          description: This is the result of the High-Level Design FTTx engieering job, based on the input provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobResult'
components:
  schemas:
    Pop:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 333
        type:
          type: string
          example: CP-AP_1496
          enum:
          - CP-AP_528
          - CP-AP_1496
          - CP-AP_1848
          - CP-AP_3696
          - AP_3696
        x:
          type: number
          format: double
          example: 52.99187331
        y:
          type: number
          format: double
          example: 5.99117733
    Cable96V:
      type: object
      properties:
        distributionPointId1:
          type: string
        distributionPointId2:
          type: string
        coreCableId:
          type: integer
          format: int64
          example: 222
        trenchIds:
          type: array
          items:
            type: string
    jobResult:
      type: object
      properties:
        status:
          type: string
        jobId:
          type: string
          format: uuid
        numberOfCoreAreas:
          type: integer
          format: int32
        amountHp:
          type: integer
          format: int32
          description: Total number of adresses after filtering on existing FttH adresses/BC received from Python
        amountHpLowRise:
          type: integer
          format: int32
          description: Total number of low-rise adresses after filtering on existing FttH adresses/BC received from Python
        amountHpHighRise:
          type: integer
          format: int32
          description: Total number of high-rise adresses after filtering on existing FttH adresses/BC received from Python
        totalCable7x14Length:
          type: number
          format: double
          description: Total length of the 7x14 ducts, received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP'
        totalCable2x14Length:
          type: number
          format: double
          description: Total length of the 2x14 ducts, received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP'
        totalCable96vLength:
          type: number
          format: double
          description: Total length of the 96fold fibercable received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP'
        totalCableDacLength:
          type: number
          format: double
          description: Total length of the DAC's, received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP'
        totalBisLength:
          type: number
          format: double
          description: Total length of digging, received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP'
        hasLength:
          type: number
          format: double
          description: Total length of lead-ins, received from Python. Column per HP should be calculated by dividing the total length by 'Aantal HP laagbouw'
        lengthDirectionalBoring:
          type: number
          format: double
          description: Total length of Horizontal Directional Drillings (HDD), received from Python. Column per HP should not be calculated
        amountDp:
          type: number
          format: double
          description: Total number of DP's, received from Python. Column per HP should not be calculated
        ftthDeploymentCosts:
          type: number
          format: double
          description: Cost per HP to build the network, received from Python. Column Totaal should be calculated by multiplying the cost per HP with 'Aantal HP'
        incaContractCapex:
          type: number
          format: double
          description: Cost per HP to build the network according to the INCA model (simplified calculation method agreed on with the contractor), received from Python. Column Totaal should be calculated by multiplying the cost per HP with 'Aantal HP'
        incaCapex:
          type: number
          format: double
          description: Cost per HP to build the network according to the INCA model (simplified calculation method agreed on with the contractor) including some internal costs like active costs  (e.g. DSLAM), received from Python. Column Totaal should be calculated by multiplying the cost per HP with 'Aantal HP'
        maximalCableLength:
          type: number
          format: double
          description: The maximum length from household to PoP, received from Python
        distributionPoints:
          type: array
          items:
            $ref: '#/components/schemas/DistributionPoint'
        cables96v:
          type: array
          items:
            $ref: '#/components/schemas/Cable96V'
        coreCables:
          type: array
          items:
            $ref: '#/components/schemas/CoreCable'
        pops:
          type: array
          items:
            $ref: '#/components/schemas/Pop'
        splitters:
          type: array
          items:
            $ref: '#/components/schemas/Splitter'
        haslist:
          type: array
          items:
            $ref: '#/components/schemas/Has'
        trenches:
          type: array
          items:
            $ref: '#/components/schemas/Trench'
        message:
          type: string
    amzSecurityToken:
      type: string
      example: AAAAAAAAAAluX2VjEA0aCWV1LXdlc3QtMSJIMEYCIQDKnFBi14jhVzfJHKod%2FCpwTIFkAj3kttgcdNRSngk49gIhAK6DboCvbtAmjlWDG5pBgzaFV1lXC0yFZWelULkpV%2FNVKuUBCNb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNjUyNDM0MTA2NTI4Igwfybzhyrjg3aq7hbMquQHE00Xe9PiL%2BS%2BSlhrzrpOKg2y%2F5qfjbR2BrGcPpxta3EiBwUpvmXR%2F%2BqkQBG7BuJifYKaDkdnOS%2B3OzxkV2WRHnKnlNwann1vCLTS9AWGdNRFLE72iJ2s%2BT3lwQp%2BR6bGMjcfqEDm84MR3gINTpSp84y9bt9hoxtxfXzF8SfGv5LVoN45K8Rf%2B%2BqF7%2BwF03JWV50Klauq4hneHRiyWsUgQY6pFMN14xj83Jn5fxKJi0L7qh%2BWBfMnDCTCW1%2Fv%2FBTrfAbwZuNzIkBmhmHsmDO9hS2dLEfqpH9GpPUl8YLY3vfjATqpjnz241WrrBdyTawUFbiTEbcKx05dUwbkUdLRP2i9CZVLAl%2Bqk0J6VYmIEhhU2RS54oHCZzinEVzsdo%2BS5eXRQ9BiAD8OCH2gP3a7bXDx9HOBxSdbGMv5mXMeP1wsdjC7e%2FkVsQlEtBTNgc62EiloUbQlPiQyb1OQEMMGZd%2BV5N%2FxdNq%2For1UraAbvxAAzGHUqQff4rmZCEDbO5uv2kwWDR1boarpQeEG8Q3j%2BxSNde%2FG%2BUjg425uIAAAAAAAAAA
      description: Additional credential parameter. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    error:
      type: object
      properties:
        transactionId:
          type: string
          description: transaction id of the the request
          title: Transaction ID
        status:
          type: string
          description: Status
          title: Status
        name:
          type: string
          description: Error name
          title: Error name
        message:
          type: string
          description: Error message
          title: Error message
        info:
          type: string
          description: Additional information about error
          title: Info
    amzSignedHeaders:
      type: string
      example: host
      description: Lists the headers used to calculate the signature. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    Splitter:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 754
        type:
          type: string
          example: Splitter
        x:
          type: number
          format: double
          example: 52.99187331
        y:
          type: number
          format: double
          example: 5.99117733
    jobStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - queued
          - accepted
          - running
          - done
          - failed
          - unknown
    DistributionPoint:
      type: object
      properties:
        id:
          type: string
        x:
          type: number
          format: double
        y:
          type: number
          format: double
        hhRoutes:
          type: array
          items:
            $ref: '#/components/schemas/HHRoute'
      required:
      - id
      - x
      - y
      - hhRoutes
    HHRoute:
      type: object
      properties:
        trenchIds:
          type: array
          items:
            type: string
    Has:
      type: object
      description: Has geo properties
      properties:
        id:
          type: string
          example: HAS 1127PV189
        x1:
          type: number
          format: double
        y1:
          type: number
          format: double
        x2:
          type: number
          format: double
        y2:
          type: number
          format: double
    amzSignature:
      type: string
      example: aaaaaaaaaa09c013193ffd301019b60308a092c972b22fdfcb8424bbbbbbbbbb
      description: The signature to authenticate your request. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    amzCredential:
      type: string
      example: AAAAAA%2F20201201%2Feu-west-1%2Fs3%2Faws4_request
      description: This parameter provides scope (AWS region and service) for which the signature is valid. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    signedOutputUrl:
      type: object
      properties:
        signedUrl:
          type: string
          format: uri
          example: https://ftth-engineering-prod.s3.amazonaws.com/Output/FTTx_AdamNorth_Input_Dec2020.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AAAAAA%2F20201201%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20201201T120000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=AAAAAAAAAAluX2VjEA0aCWV1LXdlc3QtMSJIMEYCIQDKnFBi14jhVzfJHKod%2FCpwTIFkAj3kttgcdNRSngk49gIhAK6DboCvbtAmjlWDG5pBgzaFV1lXC0yFZWelULkpV%2FNVKuUBCNb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNjUyNDM0MTA2NTI4Igwfybzhyrjg3aq7hbMquQHE00Xe9PiL%2BS%2BSlhrzrpOKg2y%2F5qfjbR2BrGcPpxta3EiBwUpvmXR%2F%2BqkQBG7BuJifYKaDkdnOS%2B3OzxkV2WRHnKnlNwann1vCLTS9AWGdNRFLE72iJ2s%2BT3lwQp%2BR6bGMjcfqEDm84MR3gINTpSp84y9bt9hoxtxfXzF8SfGv5LVoN45K8Rf%2B%2BqF7%2BwF03JWV50Klauq4hneHRiyWsUgQY6pFMN14xj83Jn5fxKJi0L7qh%2BWBfMnDCTCW1%2Fv%2FBTrfAbwZuNzIkBmhmHsmDO9hS2dLEfqpH9GpPUl8YLY3vfjATqpjnz241WrrBdyTawUFbiTEbcKx05dUwbkUdLRP2i9CZVLAl%2Bqk0J6VYmIEhhU2RS54oHCZzinEVzsdo%2BS5eXRQ9BiAD8OCH2gP3a7bXDx9HOBxSdbGMv5mXMeP1wsdjC7e%2FkVsQlEtBTNgc62EiloUbQlPiQyb1OQEMMGZd%2BV5N%2FxdNq%2For1UraAbvxAAzGHUqQff4rmZCEDbO5uv2kwWDR1boarpQeEG8Q3j%2BxSNde%2FG%2BUjg425uIAAAAAAAAAA&X-Amz-Signature=aaaaaaaaaa09c013193ffd301019b60308a092c972b22fdfcb8424bbbbbbbbbb
    jsonFileNameSchema:
      type: string
      example: FTTx_AdamNorth_Input_Dec2020
    amzDate:
      type: string
      example: 20201201T120000Z
      description: The date when the signedUrl was generated. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    amzExpires:
      type: string
      example: '3600'
      description: Provides the time period, in seconds, for which the generated presigned URL is valid. Use the value provided as part of the signed URL response of /startJobS3 or /jobResultS3.
    jsonFileNameAndExtensionSchema:
      type: string
      pattern: ^.+\.(json)$
      example: FTTx_AdamNorth_Input_Dec2020.json
      description: "The `jobId` of the engineering job you defined in /startJobS3 or /jobResultS3 with added .json extension. \n"
    Trench:
      type: object
      description: Trench properties
      properties:
        id:
          type: string
          example: 1005_up_12800
        x1:
          type: number
          format: double
        y1:
          type: number
          format: double
        x2:
          type: number
          format: double
        y2:
          type: number
          format: double
        length:
          type: number
          format: double
        surfaceType:
          type: string
          enum:
          - premium_road
          - road
          example: road
    amzAlgorithm:
      type: string
      example: AWS4-HMAC-SHA256
      description: Identifies the version of AWS Signature and the algorithm used to calculate the signature. Use the value provided as part of the signed URL response of `/startJobS3` or `/jobResultS3`.
    CoreCable:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 222
        popId:
          type: integer
          format: int64
          example: 333
        trenchIds:
          type: array
          items:
            type: string
  responses:
    bad_request:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    gateway_error:
      description: gateway_error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    not_found:
      description: not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    too_many:
      description: too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    service_unavailable:
      description: service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    forbidden:
      description: forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    server_error:
      description: server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes: {}
externalDocs:
  description: HTTP response headers
  url: https://developer.kpn.com/documentation-response-headers