openapi: 3.0.3
info:
  title: Telenor Connexion Reports API
  description: >
    API responsible for listing and fetching reports.

    This is an API intended for software developers and system
    integrators implementing client applications for management of IoT
    devices. It is assumed that the reader is familiar with software API
    concepts such as REST, JSON and OpenAPI interface specification see [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification).

    ### Response Codes

    This API follows standard response codes for REST APIs please refer to [W3C response codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
  license:
    name: Telenor Connexion Public License - v 1.0
    url: https://www.telenorconnexion.com
  termsOfService: https://www.telenorconnexion.com/terms-of-service
  contact:
    name: Telenor Connexion Support
    email: cno@telenorconnexion.com
  version: 2.0.1
servers:
- url: https://api.iot.telenor.com
paths:
  /iot-connect/reports/v1/traffic/aggregated/{domainId}:
    get:
      description: List available aggregated traffic reports.
      operationId: ListAggregatedTrafficReports
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseTrafficAggregated'
        400: &400-error
          $ref: '#/components/responses/Error400'
        401: &401-error
          description: Invalid or missing ID Token (JWT).
        500: &500-error
          $ref: '#/components/responses/Error500'
      x-amazon-apigateway-integration: &lambda-config
        credentials:
          Fn::Sub: ${ApiRole.Arn}
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${ReportsFunc.Arn}:current/invocations
        passthroughBehavior: when_no_match
        httpMethod: POST
        type: aws_proxy

  /iot-connect/reports/v1/traffic/aggregated/{domainId}/{yearMonth}:
    get:
      description: Fetch aggregated traffic report for a specific month.
      operationId: GetAggregatedTrafficReport
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonth'
      responses: &single-report-responses
        200:
          $ref: '#/components/responses/GetReportResponse'
        400: *400-error
        401: *401-error
        404: &404-error
          $ref: '#/components/responses/Error404'
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/sms/{domainId}:
    get:
      description: List available SMS traffic reports.
      operationId: ListSMSTrafficReports
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseTrafficSMS'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/sms/{domainId}/{yearMonthDay}:
    get:
      description: Get SMS traffic report for a specific day.
      operationId: GetSMSTrafficReport
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonthDay'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/data/{domainId}:
    get:
      description: List available data traffic reports.
      operationId: ListDataTrafficReports
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseTrafficData'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/data/{domainId}/{yearMonthDay}:
    get:
      description: Get data traffic report for a specific day.
      operationId: GetDataTrafficReport
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonthDay'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/voice/{domainId}:
    get:
      description: List available voice traffic reports.
      operationId: ListVoiceTrafficReports
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseTrafficVoice'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/traffic/voice/{domainId}/{yearMonthDay}:
    get:
      description: Get voice traffic report for a specific day.
      operationId: GetVoiceTrafficReport
      tags:
        - Traffic reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonthDay'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/billing/details/{domainId}:
    get:
      description: List available detailed billing reports.
      operationId: ListBillingDetailsReports
      tags:
        - Billing reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseBillingDetails'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/billing/details/{domainId}/{yearMonth}:
    get:
      description: Get detailed billing report for a specific month.
      operationId: GetDetailedBillingReport
      tags:
        - Billing reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonth'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/subscription/state/{domainId}:
    get:
      description: List available subscription state reports.
      operationId: ListSubscriptionStateReports
      tags:
        - Subscription state reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseSubscriptionState'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/subscription/state/{domainId}/{yearMonth}:
    get:
      description: Get subscription state report for a specific month.
      operationId: GetSubscriptionStateReport
      tags:
        - Subscription state reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonth'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/subscription/change/{domainId}:
    get:
      description: List available subscription change reports.
      operationId: ListSubscriptionChangeReports
      tags:
        - Subscription change reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
      responses:
        200:
          $ref: '#/components/responses/ListReportsResponseSubscriptionChange'
        400: *400-error
        401: *401-error
        500: *500-error
      x-amazon-apigateway-integration: *lambda-config

  /iot-connect/reports/v1/subscription/change/{domainId}/{yearMonth}:
    get:
      description: Get subscription change report for a specific month.
      operationId: GetSubscriptionChangeReport
      tags:
        - Subscription change reports
      parameters:
        - $ref: '#/components/parameters/domainId'
        - $ref: '#/components/parameters/yearMonth'
      responses: *single-report-responses
      x-amazon-apigateway-integration: *lambda-config

  # Invoices are currently not exposed. Envoy will respond 404 for these endpoints.
  # Workshops together with the Billing and Product team is required first.
  #/iot-connect/reports/v1/billing/invoices/{domainId}:
    #get:
     # description: List available invoices.
      #operationId: ListInvoices
      #tags:
       # - Invoices
      #responses:
        #200:
         # $ref: '#/components/responses/ListReportsResponseInvoice'
        #400: *400-error
        #401: *401-error
        #500: *500-error

  #/iot-connect/reports/v1/billing/invoices/{domainId}/{yearMonth}:
    #get:
     # description: Get invoice for a specific month.
      #operationId: GetInvoice
      #tags:
       # - Invoices
      #parameters:
       # - $ref: '#/components/parameters/yearMonth'
      #responses:
       # 200:
        #  $ref: '#/components/responses/GetInvoiceResponse'
        #400: *400-error
        #401: *401-error
        #404: *404-error
        #500: *500-error
      #security: *security

components:
  parameters:
    yearMonth:
      description: Year and month, written in YYYY-MM format.
      required: true
      name: yearMonth
      in: path
      schema:
        type: string
        pattern: '[0-9]{4}-[0-9]{2}'
        example: '2019-11'

    yearMonthDay:
      description: Year, month and day, written in YYYY-MM-DD format.
      required: true
      name: yearMonthDay
      in: path
      schema:
        type: string
        format: date

    domainId:
      description: Domain the resource belongs to. Used to determine which users have access to the resource.
      required: true
      name: domainId
      in: path
      schema:
        type: string
        pattern: ^([A-Za-z0-9]{8}-){0,6}[A-Za-z0-9]{8}$

    startDate:
      description: Start date, written in YYYY-MM-DD or YYYY-MM format.
      name: startDate
      in: query
      schema:
        type: string
        format: date

    endDate:
      description: End date, written in YYYY-MM-DD or YYYY-MM format.
      name: endDate
      in: query
      schema:
        type: string
        format: date

  responses:
    ListReportsResponse:
      description: List of reports of the specified type.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ReportListElement'

    ListReportsResponseTrafficAggregated:
      description: List of aggregated traffic reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/traffic/aggregated/2019-01'

    ListReportsResponseTrafficSMS:
      description: List of SMS traffic reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01-28'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/traffic/sms/2019-01-28'

    ListReportsResponseTrafficData:
      description: List of data traffic reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01-28'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/traffic/data/2019-01-28'

    ListReportsResponseTrafficVoice:
      description: List of voice traffic reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01-28'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/traffic/voice/2019-01-28'

    ListReportsResponseBillingDetails:
      description: List of detailed billing reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/billing/details/2019-01'

    ListReportsResponseSubscriptionState:
      description: List of subscription state reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/subscription/state/2019-01'

    ListReportsResponseSubscriptionChange:
      description: List of subscription change reports.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the report covers.
                      example: '2019-01'
                    resource:
                      type: string
                      description: Path where the report can be downloaded.
                      example: '/reports/subscription/change/2019-01'

    ListReportsResponseInvoice:
      description: List of invoices.
      content:
        application/json:
          schema:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/ReportListElement'
                - properties:
                    period:
                      type: string
                      description: The period the invoice covers.
                      example: '2019-01'
                    fileFormat:
                      type: string
                      description: The file format of the invoice.
                      example: pdf
                    resource:
                      type: string
                      description: Path where the invoice can be downloaded.
                      example: '/reports/billing/invoices/2019-01'

    GetReportResponse:
      description: The requested report. Will always be gzipped.
      headers: &report-response-headers
        Content-Disposition:
          schema:
            type: string
            description: Filename of the report to download.
            example: 'attachment; filename=2019-10-29-100-DATA-traffic-report.csv.gz'
      content:
        application/gzip:
          schema:
            type: string
            format: binary

    GetInvoiceResponse:
      description: The requested invoice. Will always be in pdf format.
      headers: *report-response-headers
      content:
        application/pdf:
          schema:
            type: string
            format: binary

    Error400:
      description: Bad request. The server cannot process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400Body'

    Error404:
      description: Entity not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404Body'

    Error500:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error500Body'

  schemas:
    ReportListElement:
      description: Description of a single report
      type: object
      properties:
        period:
          type: string
          description: The period the report covers.
          example: '2019-01'
        resource:
          type: string
          description: Path where the report can be downloaded.
          example: '/reports/traffic/aggregated/2019-01'
        fileFormat:
          type: string
          description: The file format of the report.
          example: gzip
        size:
          type: number
          description: Size of the report in bytes.
          example: 1024

    ErrorBody:
      description: Error message
      type: object
      properties:
        description:
          description: Human readable description of the error
          type: string
          example: Requested resource does not exist.
        errorCode:
          type: string
          description: String constant describing the error.
          example: RESOURCE_NOT_FOUND
        timestamp:
          description: ISO 8601 timestamp specifying when error occurred.
          type: string
          format: date-time

    Error400Body:
      allOf:
        - $ref: '#/components/schemas/ErrorBody'
        - properties:
            description:
              example: Invalid parameter.
            errorCode:
              example: INVALID_REQUEST
    Error404Body:
      allOf:
        - $ref: '#/components/schemas/ErrorBody'

    Error500Body:
      allOf:
        - $ref: '#/components/schemas/ErrorBody'
        - properties:
            description:
              example: Internal server error.
            errorCode:
              example: UNKNOWN_ERROR
