internal-subscriptions-sync-api-spec.yaml

openapi: "3.0.2"
info:
  title: "internal-subscriptions-sync-api"
  description: "REST interface for the internal-subscriptions-sync- service. Please note any deprecated APIs. Our current deprecation policy is to keep deprecated APIs around for at least 6 months."
  version: 1.0.0

servers:
  - url: /{PATH_PREFIX}/{APP_NAME}
    variables:
      PATH_PREFIX:
        default: api
      APP_NAME:
        default: rhsm-subscriptions
  - url: https://{HOSTNAME}/{PATH_PREFIX}/{APP_NAME}
    variables:
      HOSTNAME:
        enum:
          - ci.cloud.redhat.com
          - qa.cloud.redhat.com
          - stage.cloud.redhat.com
          - cloud.redhat.com
        default: ci.cloud.redhat.com
      PATH_PREFIX:
        default: api
      APP_NAME:
        default: rhsm-subscriptions

paths:
  /v1/internal/subscriptions/prune:
    description: Remove subscription and capacity records that are in the denylist.
    delete:
      summary: Remove subscription and capacity records that are in the denylist.
      operationId: pruneUnlistedSubscriptions
      tags:
        - internalSubscriptions
      responses:
        '200':
          description: Prune of unlisted subscriptions is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RpcResponse"
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"

  /v1/internal/subscriptions/rhmUsageContext:
    description: "Get the Red Hat Marketplace usage context."
    parameters:
      - name: orgId
        in: query
        required: true
        schema:
          type: string
        description: "Customer's Org Id"
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: productId
        in: query
        required: true
        schema:
          type: string
      - name: sla
        in: query
        schema:
          type: string
      - name: usage
        in: query
        schema:
          type: string
    get:
      summary: "Lookup necessary info to submit a usage record to RHM"
      operationId: getRhmUsageContext
      responses:
        '200':
          description: "Found RHM usage context matching the criteria."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RhmUsageContext'
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"
      tags:
        - internalSubscriptions
  /v1/internal/subscriptions/awsUsageContext:
    description: "Get AWS usage context."
    parameters:
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date-time
      - name: productId
        in: query
        required: true
        schema:
          type: string
      - name: orgId
        in: query
        required: true
        schema:
          type: string
        description: "Customer's Org Id"
      - name: sla
        in: query
        schema:
          type: string
      - name: usage
        in: query
        schema:
          type: string
      - name: awsAccountId
        in: query
        schema:
          type: string
          default: _ANY

    get:
      summary: "Lookup necessary info to submit a usage record to AWS"
      operationId: getAwsUsageContext
      responses:
        '200':
          description: "Found AWS usage context matching the criteria."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwsUsageContext'
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"
      tags:
        - internalSubscriptions

  /v1/internal/subscriptions/azureUsageContext:
    get:
      operationId: getAzureMarketplaceContext
      summary: Lookup necessary info to submit a usage record to Azure
      tags:
        - internalSubscriptions
      parameters:
        - name: date
          description: 'Look at subscriptions starting on this date'
          example: 2023-10-31T00:00:00Z
          schema:
            format: date-time
            type: string
          in: query
          required: true
        - name: productId
          description: 'This value should correspond to a product variant tag as defined in swatch product configuration'
          example: rhel-for-x86-els-payg
          schema:
            type: string
          in: query
          required: true
        - name: orgId
          description: 'Look at subscriptions for this orgId'
          example: org123
          schema:
            type: string
          in: query
          required: true
        - name: sla
          description: 'Look at subscriptions matching this SLA'
          example: Premium
          schema:
            type: string
          in: query
        - name: usage
          description: 'Look at subscriptions matching this usage'
          example: Production
          schema:
            type: string
          in: query
        - name: azureAccountId
          description: 'Look at subscriptions matching this billing_account_id'
          schema:
            type: string
            default: _ANY
          in: query
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AzureUsageContext'
          description: Found Azure usage context matching the criteria.
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"
  /v1/internal/tags/{tag}/metrics:
    description: "Mapping sku to product tags."
    parameters:
      - name: tag
        in: path
        required: true
        schema:
          type: string
    get:
      summary: "Lookup metric information by tag"
      operationId: getMetrics
      responses:
        '200':
          description: Matching metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Metric'
              example:
                data:
                  - metric_id: foo
                    aws_dimension: foo1
                    billing_factor: 0.25
                  - metric_id: bar
                    aws_dimension: bar1
                    billing_factor: 1.0
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"
      tags:
        - internalSubscriptions
  /v1/internal/subscriptions/terminate/{subscription_id}:
    description: "Terminate a subscription with a given end date."
    parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
        description: "Subscription ID to terminate."
    post:
      operationId: terminateSubscription
      summary: "Terminate a subscription."
      parameters:
        - name: timestamp
          description: "The termination timestamp to use."
          in: query
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: "The termination request was successful"
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TerminationRequest"
        '400':
          $ref: "../../../spec/error-responses.yaml#/$defs/BadRequest"
        '403':
          $ref: "../../../spec/error-responses.yaml#/$defs/Forbidden"
        '404':
          $ref: "../../../spec/error-responses.yaml#/$defs/ResourceNotFound"
        '500':
          $ref: "../../../spec/error-responses.yaml#/$defs/InternalServerError"
      tags:
        - internalSubscriptions
  /internal-subscription-sync-openapi.json:
    $ref: "../../../spec/openapi-paths.yaml#/openapi-json"
  /internal-subscription-sync-openapi.yaml:
    $ref: "../../../spec/openapi-paths.yaml#/openapi-yaml"

components:
  schemas:
    RhmUsageContext:
      description: Encapsulates all data needed to map tally snapshot usage to AWS UsageRecords.
      properties:
        rhSubscriptionId:
          type: string
    AwsUsageContext:
      description: Encapsulates all data needed to map tally snapshot usage to AWS UsageRecords.
      properties:
        rhSubscriptionId:
          type: string
        customerId:
          type: string
        productCode:
          type: string
        awsSellerAccountId:
          type: string
        subscriptionStartDate:
          type: string
          format: date-time
    AzureUsageContext:
      description: Encapsulates all data needed to map tally snapshot usage to Azure UsageRecords.
      properties:
        azureResourceId:
          description: IT Partner gateway will pass it under "cloudIdentifiers".  UMB messages under purchase.resourceId
          type: string
          example: 10d3a42f-cad5-4b55-8cd7-1569edf07a4d
        azureTenantId:
          description: IT Partner gateway will pass it under "cloudIdentifiers".  UMB messages under partnerIdentities.azureTenantId
          type: string
          example: 18087458-3905-4dea-80a4-758d69b7d2c5
        offerId:
          description: IT Partner gateway will pass it under "cloudIdentifiers".  UMB messages under purchase.vendorProductCode
          type: string
          example: azureProductCode
        planId:
          description: IT Partner gateway will pass it under "cloudIdentifiers".  UMB messages under contracts.planId
          type: string
          example: rh-rhel-sub-1yr
    Metric:
      properties:
        uom:
          type: string
        metric_id:
          type: string
        aws_dimension:
          type: string
        billing_factor:
          type: number
          format: double
    TerminationRequest:
      properties:
        data:
          type: object
          properties:
            termination_message:
              type: string
    RpcResponse:
      properties:
        result:
          description: Result of the operation. Empty when succeeded.
  securitySchemes:
    PskIdentity:
      type: apiKey
      in: header
      name: x-rh-swatch-psk
      description: |
        Psk header containing Pre Shared Key. Contains an
        UUID string:
        ```
        c9a98753-2092-4617-b226-5c2653330b3d
        ```

security:
  - PskIdentity: []