Red Hat 3scale Reporting API

openapi: 3.2.0
info:
  title: Red Hat 3scale Service Management Reporting API
  description: The 3scale Service Management API allows API providers to control and manage access to their APIs, track usage, and enforce traffic policies. It is used by the APIcast API gateway to authorize and report API calls in real time. The API supports both API key and OAuth 2.0 based authorization flows.
  version: '1'
  contact:
    name: Red Hat 3scale Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/agreements
servers:
- url: https://su1.3scale.net
  description: 3scale Service Management API
security:
- providerKey: []
tags:
- name: Reporting
  description: Report API usage back to 3scale for analytics and rate limiting
paths:
  /transactions/authrep.xml:
    get:
      operationId: authorizeAndReport
      summary: Authorize and Report API Transaction
      description: Combines authorization and reporting in a single call. Authorizes the API call and simultaneously reports usage metrics to 3scale. This is the recommended approach for reporting hits and other metrics.
      tags:
      - Reporting
      parameters:
      - name: provider_key
        in: query
        required: true
        description: The provider key identifying your 3scale account
        schema:
          type: string
      - name: user_key
        in: query
        required: true
        description: The API key of the application making the call
        schema:
          type: string
      - name: service_id
        in: query
        required: false
        description: The ID of the service being accessed
        schema:
          type: string
      - name: usage[hits]
        in: query
        required: false
        description: Number of hits to report
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Authorization and report successful
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
        '403':
          description: Authorization denied or limits exceeded
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeErrorResponse'
  /transactions.xml:
    post:
      operationId: reportTransactions
      summary: Report API Transactions
      description: Reports multiple API usage transactions in batch to 3scale. Used to asynchronously report usage metrics after API calls have already been processed. Supports reporting for multiple application keys in a single call.
      tags:
      - Reporting
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '202':
          description: Transactions accepted for processing
        '403':
          description: Reporting denied - invalid provider key
        '422':
          description: Invalid transaction data
components:
  schemas:
    ReportRequest:
      type: object
      required:
      - provider_key
      properties:
        provider_key:
          type: string
          description: The provider key
        service_id:
          type: string
          description: The service ID
        transactions:
          type: array
          description: Array of transaction objects to report
          items:
            type: object
    UsageReport:
      type: object
      properties:
        metric:
          type: string
          description: The metric name (e.g. hits)
        period:
          type: string
          description: The time period (minute, hour, day, month, year, eternity)
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        max_value:
          type: integer
          description: Maximum allowed value for this period
        current_value:
          type: integer
          description: Current usage value for this period
    AuthorizeErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - failure
        code:
          type: string
          description: Error code (e.g. user.exceeded_limits)
        message:
          type: string
          description: Human-readable error message
    AuthorizeResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - failure
        plan:
          type: string
          description: Name of the application plan
        usage_reports:
          type: array
          items:
            $ref: '#/components/schemas/UsageReport'
  securitySchemes:
    providerKey:
      type: apiKey
      in: query
      name: provider_key
externalDocs:
  description: Red Hat 3scale API Authentication Documentation
  url: https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.14/html/api_authentication/index