openapi: 3.0.1
info:
  title: IAM Firewall Management API Specification
  description: This specification describes the endpoints of the IAM firewall management
    service.
  version: 0-SNAPSHOT
servers:
- url: http://localhost
  description: local development host
tags:
- name: IAM Console Application Firewall Management
  description: Management functions for application firewall configurations in IAM
    Console
paths:
  /firewall/v1/applications/{application-expression}/firewall-rules:
    get:
      tags:
      - IAM Console Application Firewall Management
      summary: Get application firewall rules
      description: Read application firewall rules by application expression
      operationId: getApplicationFirewallRules
      parameters:
      - $ref: '#/components/parameters/application-expression'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationFirewallRuleV1'
            application/x-ndjson:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationFirewallRuleV1'
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
      security:
      - iam-console-token: []
    put:
      tags:
      - IAM Console Application Firewall Management
      summary: Upsert application firewall rules
      description: Create or replace a application firewall rules for an application
      operationId: upsertApplicationFirewallRules
      parameters:
      - $ref: '#/components/parameters/application-expression'
      - $ref: '#/components/parameters/returnUpdated'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ApplicationFirewallRuleInV1'
          application/x-ndjson:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ApplicationFirewallRuleInV1'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationFirewallRuleV1'
            application/x-ndjson:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationFirewallRuleV1'
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          $ref: '#/components/responses/Conflict'
      security:
      - iam-console-token: []
    delete:
      tags:
      - IAM Console Application Firewall Management
      summary: Delete application firewall rules
      description: Removes application firewall rules by application expression
      operationId: deleteApplicationFirewallRules
      parameters:
      - $ref: '#/components/parameters/application-expression'
      responses:
        "204":
          description: The request is processed and no content was returned
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          $ref: '#/components/responses/Conflict'
      security:
      - iam-console-token: []
  /firewall/v1/applications/{application-expression}/firewall-rules/{application-firewall-rule-key}:
    get:
      tags:
      - IAM Console Application Firewall Management
      summary: Get application firewall rule
      description: Read application firewall rule by its application expression and
        application firewall rule key
      operationId: getApplicationFirewallRule
      parameters:
      - $ref: '#/components/parameters/application-expression'
      - $ref: '#/components/parameters/application-firewall-rule-key'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationFirewallRuleV1'
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/ApplicationFirewallRuleV1'
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
      security:
      - iam-console-token: []
    put:
      tags:
      - IAM Console Application Firewall Management
      summary: Upsert application firewall rule
      description: Create or replace an application firewall rule by its application
        expression and application firewall rule key
      operationId: upsertApplicationFirewallRule
      parameters:
      - $ref: '#/components/parameters/application-expression'
      - $ref: '#/components/parameters/application-firewall-rule-key'
      - $ref: '#/components/parameters/returnUpdated'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationFirewallRuleInWithoutKeyV1'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationFirewallRuleV1'
        "204":
          $ref: '#/components/responses/NoContent'
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          $ref: '#/components/responses/Conflict'
      security:
      - iam-console-token: []
    delete:
      tags:
      - IAM Console Application Firewall Management
      summary: Delete application firewall rule
      description: Removes an application firewall rule by application expression
        and application firewall rule key
      operationId: deleteApplicationFirewallRule
      parameters:
      - $ref: '#/components/parameters/application-expression'
      - $ref: '#/components/parameters/application-firewall-rule-key'
      responses:
        "204":
          description: The request is processed and no content was returned
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "409":
          $ref: '#/components/responses/Conflict'
      security:
      - iam-console-token: []
components:
  schemas:
    ApplicationFirewallAuthorizedRoleInV1:
      required:
      - key
      type: object
      properties:
        key:
          maxLength: 64
          minLength: 1
          pattern: "^[a-zA-Z0-9-_.]{1,64}$"
          type: string
          description: "The identifier of a role, also know as 'roleKey'"
          example: ADMINISTRATOR
      description: Eligible roles that will allow passage
    ApplicationFirewallAuthorizedRoleV1:
      required:
      - key
      type: object
      properties:
        key:
          type: string
          description: "The identifier of a role, also know as 'roleKey'"
          example: ADMINISTRATOR
      description: Eligible roles that will allow passage
    ApplicationFirewallRuleInV1:
      required:
      - key
      - status
      type: object
      properties:
        key:
          maxLength: 64
          minLength: 1
          pattern: "^[a-zA-Z0-9-_.]{1,64}$"
          type: string
          description: An application firewall rule identifier
          example: firewall-rule-1
        name:
          maxLength: 64
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        description:
          maxLength: 4096
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        status:
          type: string
          description: The initial status of this rule
          enum:
          - ENABLED
          - DISABLED
        authorizationKeys:
          maxItems: 5
          minItems: 0
          type: array
          description: Details allowed firewall authorization keys that may be used
            to pass the firewall
          items:
            maxLength: 36
            minLength: 36
            pattern: "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\\
              b-[0-9a-fA-F]{12}$"
            type: string
            description: An application firewall authorization key that may be passed
              via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow
              passage.
            example: bb1b93ae-5e47-4dbc-ad74-8e684b33c0cc
        authorizedRoles:
          maxItems: 100
          minItems: 0
          type: array
          description: Eligible roles that will allow passage
          items:
            $ref: '#/components/schemas/ApplicationFirewallAuthorizedRoleInV1'
        unprotectedServices:
          maxItems: 100
          minItems: 0
          type: array
          description: Details which services and their respective permissions that
            may be called without any firewall restriction
          items:
            $ref: '#/components/schemas/ApplicationFirewallUnprotectedServiceInV1'
    ApplicationFirewallRuleInWithoutKeyV1:
      required:
      - status
      type: object
      properties:
        name:
          maxLength: 64
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        description:
          maxLength: 4096
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        status:
          type: string
          description: The initial status of this rule
          enum:
          - ENABLED
          - DISABLED
        authorizationKeys:
          maxItems: 5
          minItems: 0
          type: array
          description: Details allowed firewall authorization keys that may be used
            to pass the firewall
          items:
            maxLength: 36
            minLength: 36
            pattern: "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\\
              b-[0-9a-fA-F]{12}$"
            type: string
            description: An application firewall authorization key that may be passed
              via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow
              passage.
            example: bb1b93ae-5e47-4dbc-ad74-8e684b33c0cc
        authorizedRoles:
          maxItems: 100
          minItems: 0
          type: array
          description: Eligible roles that will allow passage
          items:
            $ref: '#/components/schemas/ApplicationFirewallAuthorizedRoleInV1'
        unprotectedServices:
          maxItems: 100
          minItems: 0
          type: array
          description: Details which services and their respective permissions that
            may be called without any firewall restriction
          items:
            $ref: '#/components/schemas/ApplicationFirewallUnprotectedServiceInV1'
    ApplicationFirewallRuleV1:
      required:
      - applicationId
      - changeId
      - createdAt
      - createdBy
      - key
      - lastModifiedAt
      - lastModifiedBy
      - status
      type: object
      properties:
        applicationId:
          type: string
          description: The globally unique identifier for an application
        key:
          type: string
          description: An application firewall rule identifier
        name:
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        description:
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        status:
          type: string
          description: Declares if this rule is enforced or not
        authorizationKeys:
          type: array
          description: Details allowed firewall authorization keys that may be used
            to pass the firewall
          items:
            type: string
            description: An application firewall authorization key that may be passed
              via the firewall security header 'APPLICATION-FIREWALL-KEY' to allow
              passage.
        authorizedRoles:
          type: array
          description: Eligible roles that will allow passage
          items:
            $ref: '#/components/schemas/ApplicationFirewallAuthorizedRoleV1'
        unprotectedServices:
          type: array
          description: Details which services and their respective permissions that
            may be called without any firewall restriction
          items:
            $ref: '#/components/schemas/ApplicationFirewallUnprotectedServiceV1'
        createdAt:
          type: string
          description: UTC date time when entity was created. This string is formatted
            according to RFC3339.
          format: date-time
        createdBy:
          type: string
          description: The globally unique identifier for an actor
        lastModifiedAt:
          type: string
          description: UTC date time when entity was modified. This string is formatted
            according to RFC3339.
          format: date-time
        lastModifiedBy:
          type: string
          description: The globally unique identifier for an actor
        changeId:
          type: string
          description: Text representation of changeId sequence number
          example: "7380283282446876762"
    ApplicationFirewallUnprotectedServiceInV1:
      required:
      - serviceDefinitionKey
      - serviceDefinitionSource
      type: object
      properties:
        serviceDefinitionSource:
          type: string
          description: The service definition source describes the origin of the definition
          enum:
          - APPLICATION
          - CATALOG
        serviceDefinitionKey:
          maxLength: 64
          minLength: 1
          pattern: "^[a-zA-Z0-9-_.]{1,64}$"
          type: string
          description: Identifies a service definition by its key
          example: exercise-tracking-service
        unprotectedPermissions:
          maxItems: 100
          minItems: 0
          type: array
          description: An array of permissions that will be ignored by the firewall
            for the given service. If the list is empty/null then all permissions
            are unprotected by the firewall
          items:
            maxLength: 64
            minLength: 1
            pattern: "^[a-zA-Z0-9-_.]{1,64}$"
            type: string
            description: Identifies a permission definition by its key for a service
            example: read
      description: Details which services and their respective permissions that may
        be called without any firewall restriction
    ApplicationFirewallUnprotectedServiceV1:
      required:
      - serviceDefinitionKey
      - serviceDefinitionSource
      type: object
      properties:
        serviceDefinitionSource:
          type: string
          description: The service definition source describes the origin of the definition
        serviceDefinitionKey:
          type: string
          description: Identifies a service definition by its key
        unprotectedPermissions:
          type: array
          description: An array of permissions that will be ignored by the firewall
            for the given service. If the list is empty/null then all permissions
            are unprotected by the firewall
          items:
            type: string
            description: Identifies a permission definition by its key for a service
      description: Details which services and their respective permissions that may
        be called without any firewall restriction
    ErrorDetailV1:
      required:
      - code
      type: object
      properties:
        field:
          type: string
          description: A reference to a field or parameter which cannot be processed
        code:
          type: string
          description: "A code which indicated the type of error, documented per service"
        message:
          type: string
          description: "Additional information, intended for developers"
      description: "Additional error details, usually used for form validation. Documented\
        \ per service and endpoint."
    ErrorV1:
      required:
      - errorId
      type: object
      properties:
        errorId:
          type: string
          description: "An error identifier for the request, to be provided in troubleshooting."
        code:
          type: string
          description: An error code which describes this error. Documented per service
            and endpoint.
        message:
          type: string
          description: A human readable message of error. Intended for developers.
        details:
          type: array
          description: "Additional error details, usually used for form validation.\
            \ Documented per service and endpoint."
          items:
            $ref: '#/components/schemas/ErrorDetailV1'
  responses:
    NoContent:
      description: The request is processed and no content was returned
    BadRequest:
      description: "The request is malformed, see error data for additional information"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
    Unauthorized:
      description: The request did not have valid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
    Forbidden:
      description: The requester is not authorized to perform this action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
    NotFound:
      description: The resource could not be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
    Conflict:
      description: "The request could not be processed due to a conflict in state,\
        \ see error data for additional information"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
  parameters:
    application-expression:
      name: application-expression
      in: path
      required: true
      schema:
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
        description: "Used to identify a specific applicationId. The available options\
          \ are: \n* '{applicationId}' - direct applicationId reference"
    application-firewall-rule-key:
      name: application-firewall-rule-key
      in: path
      required: true
      schema:
        type: string
        description: An application firewall rule identifier
    returnUpdated:
      name: returnUpdated
      in: query
      description: To return the entity after successful update or not
      schema:
        type: boolean
        default: false
  securitySchemes:
    iam-console-token:
      type: http
      scheme: bearer
      bearerFormat: IAM issued jwt token for the IAM console application