near-rt-ric-simulator/api/1.1.x-alpha.2/a1-openapi.yaml

openapi: 3.0.0
info:
  title: 'A1-P Policy Management Service'
  version: 1.1.x-alpha.2
  description: |
    API for Policy Management Service.
    © 2019, O-RAN Alliance.
    All rights reserved.
externalDocs:
  description: 'ORAN-WG2.A1.AP-v01.01 A1 interface: Application protocol'
  url: 'https://www.o-ran.org/specifications'
servers:
  - url: '{apiRoot}/A1-P/v1'
    variables:
      apiRoot:
        default: 'https://example.com'
        description: 'apiRoot as defined in clause 4.2.1 in ORAN-WG2.A1.AP'
paths:
  '/policies':
    get:
      operationId: a1.get_all_policy_identities
      description: 'Get all policy identities'
      tags:
      - All Policy Identities
      parameters:
        - name: policyTypeId
          in: query
          required: false
          schema:
            "$ref": "#/components/schemas/PolicyTypeId"
      responses:
        200:
          description: 'Array of all policy identities'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyId"
                minItems: 0
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"

  '/policies/{policyId}':
    parameters:
      - name: policyId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyId"
    put:
      operationId: a1.put_policy
      description: 'Create, or update, a policy'
      tags:
      - Individual Policy Object
      parameters:
        - name: policyTypeId
          in: query
          required: false
          schema:
            "$ref": "#/components/schemas/PolicyTypeId"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PolicyObject"
      responses:
        200:
          description: 'The policy was updated'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
        201:
          description: 'The policy was created'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
          headers:
            Location:
              description: 'Contains the URI of the created policy'
              required: true
              schema:
                type: string
        400:
          "$ref": "#/components/responses/400-BadRequest"
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"
        507:
          "$ref": "#/components/responses/507-InsufficientStorage"
    get:
      operationId: a1.get_policy
      description: 'Query a policy'
      tags:
      - Individual Policy Object
      responses:
        200:
          description: 'The requested policy'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyObject"
        404:
          "$ref": "#/components/responses/404-NotFound"
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"
    delete:
      operationId: a1.delete_policy
      description: 'Delete a policy'
      tags:
      - Individual Policy Object
      responses:
        204:
          description: 'The policy was deleted'
        404:
          "$ref": "#/components/responses/404-NotFound"
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"

  '/policystatus/{policyId}':
    parameters:
      - name: policyId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyId"
    get:
      operationId: a1.get_policy_status
      description: 'Query a policy status'
      tags:
      - Individual Policy Status Object
      responses:
        200:
          description: 'The requested policy status'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyStatusObject"
        404:
          "$ref": "#/components/responses/404-NotFound"
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"

  '/policytypes':
    get:
      operationId: a1.get_all_policytypes_identities
      description: 'Get all policy type identities'
      tags:
      - All Policy Type Identities
      responses:
        200:
          description: 'Array of all policy type identities'
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PolicyTypeId"
                minItems: 0
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"

  '/policytypes/{policyTypeId}':
    parameters:
      - name: policyTypeId
        in: path
        required: true
        schema:
          "$ref": "#/components/schemas/PolicyTypeId"
    get:
      operationId: a1.get_policytypes
      description: 'Get the schemas for a policy type'
      tags:
      - Individual Policy Type
      responses:
        200:
          description: 'The policy type schemas'
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PolicyTypeObject"
        404:
          "$ref": "#/components/responses/404-NotFound"
        429:
          "$ref": "#/components/responses/429-TooManyRequests"
        503:
          "$ref": "#/components/responses/503-ServiceUnavailable"

components:
  schemas:
    #
    # Representation objects
    #
    PolicyObject:
      description: 'A generic policy object that can be used to transport any policy. Additionally, a policy shall be valid according to the schema of its specific policy type.'
      type: object

    PolicyStatusObject:
      description: 'A generic policy status object that can be used to transport any policy status. Additionally, a policy status shall be valid according to the schema of its specific policy type.'
      type: object

    PolicyTypeObject:
      description: 'A definition of a policy type, i.e. the schemas for a policy respectively its status'
      type: object
      properties:
        policySchema:
          "$ref": "#/components/schemas/JsonSchema"
        statusSchema:
          "$ref": "#/components/schemas/JsonSchema"
      required:
        - policySchema

    ProblemDetails:
      description: 'A problem detail to carry details in a HTTP response according to RFC 7807 extended with A1 specific attributes'
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: number
        detail:
          type: string
        instance:
          type: string
        cause:
          type: string
        invalidParams:
          type: array
          items:
            "$ref": "#/components/schemas/InvalidParam"
          minItems: 1

    #
    # Structured data types
    #
    InvalidParam:
      description: 'Used in a ProblemDetails to indicate a specific invalid parameter'
      type: object
      properties:
        param:
          type: string
        reason:
          type: string
      required:
        - param

    #
    # Simple data types
    #
    JsonSchema:
      description: 'A JSON schema following http://json-schema.org/draft-07/schema'
      type: object

    PolicyId:
      description: 'Policy identifier assigned by the A1-P Consumer when a policy is created'
      type: string

    PolicyTypeId:
      description: 'Policy type identifier assigned by the A1-P Provider'
      type: string

  responses:
    400-BadRequest:
      description: 'Object in payload not properly formulated or not related to the method'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    404-NotFound:
      description: 'No resource found at the URI'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    405-MethodNotAllowed:
      description: 'Method not allowed for the URI'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    429-TooManyRequests:
      description: 'Too many requests have been sent in a given amount of time'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    503-ServiceUnavailable:
      description: 'The provider is currently unable to handle the request due to a temporary overload'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"

    507-InsufficientStorage:
      description: 'The method could not be performed on the resource because the provider is unable to store the representation needed to successfully complete the request'
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ProblemDetails"