openapi: 3.0.3
info:
  title: Orders API
  description: >
    API used to manage SGP.22/32 orders and operations.
  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: 1.0.1
servers:
- url: https://api.iot.telenor.com
paths:
  /iot-connect/orders/v1/activation-codes:
    get:
      x-amazon-apigateway-integration: &aws-gateway
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${OrdersApiLambda.Arn}/invocations
        passthroughBehavior: when_no_match
        httpMethod: POST
        type: aws_proxy
      tags:
        - Activation code order
      summary: Retrieve activation code orders.
      description: Retrieves activation code orders, optionally filtered by query parameters.
      parameters:
        - name: domainId
          in: query
          required: false
          schema:
             $ref: '#/components/schemas/domainId'
          description: Filter orders by a specific domain ID.
        - name: orderStatus
          in: query
          required: false
          schema:
             $ref: '#/components/schemas/orderStatus'
          description: Filter orders by a specific order status.
      responses:
        200:
          description: A list of activation code orders.
          content:
              application/json:
                schema:
                  type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/activationCodeOrder'
        400: &error-400
          $ref: '#/components/responses/problemResponse'
        429: &error-429
          $ref: '#/components/responses/problemResponse'
        500: &error-500
          $ref: '#/components/responses/problemResponse'

    post:
      x-amazon-apigateway-integration: *aws-gateway
      tags:
        - Activation code order
      summary: Create a new activation code order.
      description: Creates an activation code order based on the supplied parameters.
      requestBody:
        description: Payload for creating an activation code order.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createActivationCodeOrder'
      responses:
        201:
          description: Activation code order created successfully.
          headers:
            Location:
              $ref: '#/components/headers/location'
        400: *error-400
        429: *error-429
        500: *error-500

  /iot-connect/orders/v1/activation-codes/{orderId}:
    get:
      x-amazon-apigateway-integration: *aws-gateway
      tags:
        - Activation code order
      summary: Retrieve an activation code order.
      description: Retrieves activation code order for the specific order ID.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
             $ref: '#/components/schemas/orderId'
          description: The order ID.
      responses:
        200:
          description: A single activation code order.
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/activationCodeOrder'
                  
        404:
          $ref: '#/components/responses/problemResponse'
        429: *error-429
        500: *error-500

components:
  schemas:
    activationCodeOrder:
      type: object
      required:
        - orderId
        - domainId
        - orderParams
        - orderStatus
        - createdBy
        - createdAt
        - updatedAt
      properties:
        orderId: 
          $ref: '#/components/schemas/orderId'
        domainId:
          $ref: '#/components/schemas/domainId'
        orderParams:
          $ref: '#/components/schemas/activationCodeOrderParams'
        orderStatus: 
          $ref: '#/components/schemas/orderStatus'
        orderNote:
          $ref: '#/components/schemas/orderNote'
        createdBy: 
          $ref: '#/components/schemas/createdBy'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    createActivationCodeOrder:
      type: object
      required:
        - domainId
        - orderParams
      properties:
        domainId:
          $ref: '#/components/schemas/domainId'
        orderParams:
          $ref: '#/components/schemas/activationCodeOrderParams'
        orderNote:
          $ref: '#/components/schemas/orderNote'

    orderId:
      type: integer
      description: A unique order ID.

    domainId:
      type: string
      description: Domain the resource belongs to. Used to determine which users have access to the resource.
      pattern: ^([A-Za-z0-9]{8}-){0,6}[A-Za-z0-9]{8}$
      example: a1ce25s2-c23edcs9
    
    orderStatus:
      type: string
      description: The current processing status of the order.
      example: IN_PROGRESS
      enum:
      - IN_PROGRESS
      - FAILED
      - COMPLETED
      - PARTIALLY_COMPLETED

    activationCodeOrderParams:
      type: object
      description: Parameters for the activation code order.
      required:
        - quantity
        - simProfileId
        - servicePolicyId
        - mode
      properties:
        quantity:
          type: integer
        simProfileId:
          type: string
        servicePolicyId:
          type: string
        mode:
          type: string
          enum:
          - ACTIVE
          - DEACTIVATED

    orderNote:
      type: string
      description: Order note to help identify or differentiate the order.
      maxLength: 255
      example: SGP.32 activation code order for our new IoT devices.

    createdBy:
      type: string
      description: Identifier of the user that created the order.
      example: john.doe@acme.com

    problemDetails:
      type: object
      description: RFC 9457 compliant problem details object for HTTP APIs.
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
          enum:
            - urn:api.iot.telenor.com:problems:bad-gateway
            - urn:api.iot.telenor.com:problems:bad-request
            - urn:api.iot.telenor.com:problems:gateway-timeout
            - urn:api.iot.telenor.com:problems:internal-server-error
            - urn:api.iot.telenor.com:problems:not-found
            - urn:api.iot.telenor.com:problems:too-many-requests
            # Domain-specific problem types
            - urn:api.iot.telenor.com:problems:bad-request:orders:invalid-domain-id
            - urn:api.iot.telenor.com:problems:bad-request:orders:invalid-request-body
            - urn:api.iot.telenor.com:problems:bad-request:orders:invalid-path-parameters
            - urn:api.iot.telenor.com:problems:bad-request:orders:invalid-query-parameters
            - urn:api.iot.telenor.com:problems:too-many-requests:orders:too-many-ongoing-orders
        title:
          type: string
          description: A short, human-readable summary of the problem.
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: The specified domain ID is invalid.
        instance:
          type: string
          format: uri
          description: Optional URI reference that identifies the specific occurrence of the problem.
          example: /iot-connect/orders/v1/activation-codes
        errors:
          type: array
          description: Optional array of field-level errors.
          items:
            type: object
            properties:
              detail:
                type: string
                description: Description of the validation error.
                example: Field X must be a positive integer
              pointer:
                type: string
                description: JSON Pointer to the field that caused the error.
                example: '#/quantity'
      additionalProperties: true
      example:
        type: urn:api.iot.telenor.com:problems:bad-request
        title: Bad Request
        status: 400
        detail: Invalid request body
        errors:
          - detail: ServicePolicyId is invalid 00AA0A0A
            pointer: '#/servicePolicyId'

  headers:
    location:
      description: URI to the resource that got created.
      schema:
        type: string
        format: uri
    
  responses:
    problemResponse:
      description: RFC 9457 compliant problem details response.
      headers:
        Access-Control-Allow-Origin:
          schema:
            type: string
        Access-Control-Allow-Methods:
          schema:
            type: string
        Access-Control-Allow-Headers:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemDetails'
