TS26512_M1_ContentHostingProvisioning.yaml

openapi: 3.0.0
info:
  title: M1_ContentHostingProvisioning
  version: 2.2.3
  description: |
    5GMS AF M1 Content Hosting Provisioning API
    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.
tags:
  - name: M1_ContentHostingProvisioning
    description: '5G Media Streaming: Provisioning (M1) APIs: Content Hosting Provisioning'
externalDocs:
  description: 'TS 26.512 V17.7.0; 5G Media Streaming (5GMS); Protocols'
  url: 'https://www.3gpp.org/ftp/Specs/archive/26_series/26.512/'
servers:
  - url: '{apiRoot}/3gpp-m1/v2'
    variables:
      apiRoot:
        default: https://example.com
        description: See 3GPP TS 29.512 clause 6.1.
paths:
  /provisioning-sessions/{provisioningSessionId}/content-hosting-configuration:
    parameters:
      - name: provisioningSessionId
        in: path
        required: true
        schema:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/ResourceId'
        description: 'The resource identifier of an existing Provisioning Session.'
    post:
      operationId: createContentHostingConfiguration
      summary: 'Create (and optionally upload) the Content Hosting Configuration for the specified Provisioning Session'
      requestBody:
        description: 'A JSON representation of a Content Hosting Configuration'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentHostingConfiguration'
      responses:
        '201':
          description: 'Content Hosting Configuration Created'
          headers:
            Location:
              description: 'URL of the newly created Content Hosting Configuration (same as request URL).'
              required: true
              schema:
                $ref: 'TS26512_CommonData.yaml#/components/schemas/AbsoluteUrl'
    get:
      operationId: retrieveContentHostingConfiguration
      summary: 'Retrieve the Content Hosting Configuration of the specified Provisioning Session'
      responses:
        '200':
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHostingConfiguration'
        '404':
          description: 'Not Found'
    put:
      operationId: updateContentHostingConfiguration
      summary: 'Update the Content Hosting Configuration for the specified Provisioning Session'
      requestBody:
        description: 'A JSON representation of a Content Hosting Configuration'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentHostingConfiguration'
      responses:
        '204':
          description: 'Updated Content Hosting Configuration'
        '404':
          description: 'Not Found'
    patch:
      operationId: patchContentHostingConfiguration
      summary: 'Patch the Content Hosting Configuration for the specified Provisioning Session'
      requestBody:
        description: 'A JSON representation of a Content Hosting Configuration'
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ContentHostingConfiguration'
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/ContentHostingConfiguration'
      responses:
        '200':
          description: 'Patched Content Hosting Configuration'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentHostingConfiguration'
        '404':
          description: 'Not Found'
    delete:
      operationId: destroyContentHostingConfiguration
      summary: 'Destroy the current Content Hosting Configuration of the specified Provisioning Session'
      responses:
        '204':
          description: 'Destroyed Content Hosting Configuration'
        '404':
          description: 'Not Found'
          
  /provisioning-sessions/{provisioningSessionId}/content-hosting-configuration/purge:
    parameters:
        - name: provisioningSessionId
          in: path
          required: true
          schema:
            $ref: 'TS26512_CommonData.yaml#/components/schemas/ResourceId'
          description: A unique identifier of the Provisioning
    post:
      operationId: purgeContentHostingCache
      summary: 'Purge the content of the cache for the Content Hosting Configuration of the specified Provisioning Session'
      requestBody:
        description: 'The regular expression pattern for resources to purge from the cache'
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                pattern: 
                  description: 'The regular expression'
                  type: string
      responses:
        '200':
          # OK
          description: 'Content Purged'
          content:
            application/json:
              schema:
                description: 'The aggregate number of cache entries purged in all 5GMSd AS instances distributing content for the requested Provisioning Session.'
                type: integer
                minimum: 1
        '204':
          # No Content
          description: 'No Content Purged'
        '400':
          # Bad Request (e.g. syntactically invalid regular expression in request body)
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '404':
          # Not Found
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '413':
          # Payload Too Large
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '414':
          # URI Too Long
          $ref: 'TS29571_CommonData.yaml#/components/responses/414'
        '415':
          # Unsupported Media Type
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '500':
          # Internal Server Error
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '503':
          # Service Unavailable
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'

components:
  schemas:
    IngestConfiguration:
      type: object
      description: 'A configuration for content ingest.'
      properties:
        pull:
          type: boolean
        protocol:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        baseURL:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/AbsoluteUrl'

    M1MediaEntryPoint:
      description: "A typed entry point for downlink or uplink media streaming."
      type: object
      required:
        - relativePath
        - contentType
      properties:
        relativePath:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/RelativeUrl'
        contentType:
          type: string
        profiles:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
          minItems: 1

    PathRewriteRule:
      type: object
      description: 'A rule to manipulate URL paths.'
      required:
        - requestPathPattern
        - mappedPath
      properties:
        requestPathPattern:
          type: string
        mappedPath:
          type: string

    CachingConfiguration:
      type: object
      description: 'A content caching configuration.'
      required:
        - urlPatternFilter
      properties:
        urlPatternFilter:
          type: string
        cachingDirectives:
          type: object
          required:
            - noCache
          properties:
            statusCodeFilters:
              type: array
              items:
                type: integer
            noCache:
              type: boolean
            maxAge:
              type: integer
              format: int32

    DistributionConfiguration:
      type: object
      description: 'A content distribution configuration.'
      properties:
        entryPoint:
          $ref: '#/components/schemas/M1MediaEntryPoint'
        contentPreparationTemplateId:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/ResourceId'
        edgeResourcesConfigurationId:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/ResourceId'
        canonicalDomainName:
          type: string
        domainNameAlias:
          type: string
        baseURL:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/AbsoluteUrl'
        pathRewriteRules:
          type: array
          items:
            $ref: '#/components/schemas/PathRewriteRule'
        cachingConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/CachingConfiguration'
        geoFencing:
          type: object
          required:
            - locatorType
            - locators
          properties:
            locatorType:
              $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
            locators:
              type: array
              items: 
                type: string
                description: 'Format of individual locators depends on the locatorType.'
              minItems: 1
        urlSignature:
          type: object
          required:
            - urlPattern
            - tokenName
            - passphraseName
            - passphrase
            - tokenExpiryName
            - useIPAddress
          properties:
            urlPattern:
              type: string
            tokenName:
              type: string
            passphraseName:
              type: string
            passphrase:
              type: string
            tokenExpiryName:
              type: string
            useIPAddress:
              type: boolean
            ipAddressName:
              type: string
        certificateId:
          $ref: 'TS26512_CommonData.yaml#/components/schemas/ResourceId'
        supplementaryDistributionNetworks:
          type: array
          items:
            type: object
            description: "A duple tying a type of supplementary distribution network to its distribution mode."
            required:
              - distributionNetworkType
              - distributionMode
            properties:
              distributionNetworkType:
                $ref: '#/components/schemas/DistributionNetworkType'
              distributionMode:
                $ref: '#/components/schemas/DistributionMode'

    # Schema for the resource itself
    ContentHostingConfiguration:
      type: object
      description: "A representation of a Content Hosting Configuration resource."
      required:
        - name
        - ingestConfiguration
        - distributionConfigurations
      properties:
        name:
          type: string
        ingestConfiguration:
          $ref: '#/components/schemas/IngestConfiguration'
        distributionConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/DistributionConfiguration'

    DistributionNetworkType:
      description: "Type of distribution network."
      anyOf:
        - type: string
          enum: [NETWORK_EMBMS]
        - type: string
          description: >
            This string provides forward-compatibility with future
            extensions to the enumeration but is not used to encode
            content defined in the present version of this API.

    DistributionMode:
      description: "Mode of content distribution."
      anyOf:
        - type: string
          enum: [MODE_EXCLUSIVE, MODE_HYBRID, MODE_DYNAMIC]
        - type: string
          description: >
            This string provides forward-compatibility with future
            extensions to the enumeration but is not used to encode
            content defined in the present version of this API.