ChannelMappingAPI.raml

#%RAML 1.0

# AMWA NMOS Audo Channel Mapping Specification: Channel Mapping API
# (c) AMWA 2018

title: Channel Mapping
baseUri: http://api.example.com/x-nmos/channelmapping/{version}
version: v1.0
mediaType: application/json

documentation:
  - title: Overview
    content: |
      The Channel Mapping API is exposed by NMOS Devices as a standard control interface for management of audio matrix mapping inside Devices.
  - title: Further Documentation
    content: |
      Further normative documentation covering the behaviour of this API is contained in the [docs](../docs) folder of this repository.
/:
  displayName: Base
  get:
    description: List of paths available from this API
    responses:
      200:
        body:
          example: !include ../examples/base-get-200.json
          type: !include schemas/base-schema.json
/inputs:
  displayName: Inputs
  get:
    description: List all inputs available
    responses:
      200:
        body:
          example: !include ../examples/inputs/inputs-base-get-200.json
          type: !include schemas/inputs-outputs-base-schema.json
  /{inputId}:
    uriParameters:
      inputId:
        type: string
        pattern: "^[a-zA-Z0-9\\-_]+$"
    get:
      description: List of paths available from this API endpoint
      responses:
        200:
          body:
            example: !include ../examples/inputs/input-base-get-200.json
            type: !include schemas/input-base-schema.json
        404:
          description: Returned when the requested resource does not exist
    /properties:
      displayName: Input Properties
      get:
        description: Get information about the specified Input, such as a human-readable name and description
        responses:
          200:
            body:
              example: !include ../examples/inputs/input-properties-get-200.json
              type: !include schemas/input-properties-schema.json
          404:
            description: Returned when the requested resource does not exist
    /parent:
      displayName: Input Parent
      get:
        description: Get information about the origin of the audio associated with the specified Input
        responses:
          200:
            body:
              example: !include ../examples/inputs/input-parent-get-200.json
              type: !include schemas/input-parent-response-schema.json
          404:
            description: Returned when the requested resource does not exist
    /channels:
      displayName: Input Channels
      get:
        description: Get information about the specified Input's channels, such as human-readable labels
        responses:
          200:
            body:
              example: !include ../examples/inputs/input-channels-get-200.json
              type: !include schemas/input-channels-response-schema.json
          404:
            description: Returned when the requested resource does not exist
    /caps:
      displayName: Input Capabilities
      get:
        description: Get information about the specified Input's capabilities, such as routing constraints
        responses:
          200:
            body:
              example: !include ../examples/inputs/input-caps-get-200.json
              type: !include schemas/input-caps-response-schema.json
          404:
            description: Returned when the requested resource does not exist
/outputs:
  displayName: Outputs
  get:
    description: List all outputs available
    responses:
      200:
        body:
          example: !include ../examples/outputs/outputs-base-get-200.json
          type: !include schemas/inputs-outputs-base-schema.json
  /{outputId}:
    uriParameters:
      outputId:
        type: string
        pattern: "^[a-zA-Z0-9\\-_]+$"
    get:
      description: List of paths available from this API endpoint
      responses:
        200:
          body:
            example: !include ../examples/outputs/output-base-get-200.json
            type: !include schemas/output-base-schema.json
        404:
          description: Returned when the requested resource does not exist
    /properties:
      displayName: Output Properties
      get:
        description: Get information about the specified Output, such as a human-readable name and description
        responses:
          200:
            body:
              example: !include ../examples/outputs/output-properties-get-200.json
              type: !include schemas/output-properties-schema.json
          404:
            description: Returned when the requested resource does not exist
    /sourceid:
      displayName: Output Source ID
      get:
        description: Get the ID of the Source associated with the specified Output
        responses:
          200:
            body:
              example: !include ../examples/outputs/output-sourceid-get-200.json
              type: !include schemas/output-sourceid-response-schema.json
          404:
            description: Returned when the requested resource does not exist
    /channels:
      displayName: Output Channels
      get:
        description: Get information about the specified Output's channels, such as human-readable labels
        responses:
          200:
            body:
              example: !include ../examples/outputs/output-channels-get-200.json
              type: !include schemas/output-channels-response-schema.json
          404:
            description: Returned when the requested resource does not exist
    /caps:
      displayName: Output Capabilities
      get:
        description: Get information about the specified Output's capabilities, such as routing constraints
        responses:
          200:
            body:
              example: !include ../examples/outputs/output-caps-get-200.json
              type: !include schemas/output-caps-response-schema.json
          404:
            description: Returned when the requested resource does not exist
/map:
  displayName: Map
  get:
    description: List of paths available from this API endpoint
    responses:
      200:
        body:
          example: !include ../examples/map/map-base-get-200.json
          type: !include schemas/map-base-schema.json
  /activations:
    displayName: Activations
    get:
      description: List pending scheduled activations
      responses:
        200:
          body:
            example: !include ../examples/map/map-activations-get-200.json
            type: !include schemas/map-activations-get-response-schema.json
    post:
      description: Create a new activation
      body:
        type: !include schemas/map-activations-post-request-schema.json
        example: !include ../examples/map/map-activations-post.json
      responses:
        200:
          description: >
            A 200 response is returned when a request for an immediate activation is accepted.
          body:
            type: !include schemas/map-activations-post-response-schema.json
            example: !include ../examples/map/map-activations-post-200.json
        202:
          description: >
            A 202 response is returned when a request for a scheduled activation is accepted, to indicate
            that while the request itself was acceptable it has not yet been acted upon by the API.
          body:
            type: !include schemas/map-activations-post-response-schema.json
            example: !include ../examples/map/map-activations-post-200.json
        400:
          description: >
            A 400 response is returned, for example, when the request did not meet the schema.
          body:
            type: !include schemas/error.json
            example: !include ../examples/map/map-activations-post-400.json
        423:
          description: >
            A 423 response is returned when a conflicting activation has been scheduled.
          body:
            type: !include schemas/error.json
            example: !include ../examples/map/map-activations-post-423.json
    options:
      description: A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
      responses:
        200:
        403:
    /{activationId}:
      uriParameters:
        activationId:
          type: string
          pattern: "^[a-zA-Z0-9\\-_]+$"
      get:
        description: Get a single pending scheduled activation
        responses:
          200:
            body:
              example: !include ../examples/map/map-activations-activation-get-200.json
              type: !include schemas/map-activations-activation-get-response-schema.json
          404:
            description: Could not find the requested resource
      delete:
        description: Cancel a pending scheduled activation
        responses:
          204:
            description: Resource deleted successfully
          404:
            description: Could not find the requested resource
      options:
        description: A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
        responses:
          200:
          403:
  /active:
    displayName: Active Map
    get:
      description: Get a view of the entire active map
      responses:
        200:
          body:
            example: !include ../examples/map/map-active-get-200.json
            type: !include schemas/map-active-response-schema.json
    /{outputId}:
      uriParameters:
        outputId:
          type: string
          pattern: "^[a-zA-Z0-9\\-_]+$"
      get:
        description: |
          Get the active map for the specified output.
          This resource allows a controller to fetch only the section of the map related to the specified output, without the need to fetch the entire map.
        responses:
          200:
            body:
              example: !include ../examples/map/map-active-output-get-200.json
              type: !include schemas/map-active-output-response-schema.json
          404:
            description: Returned when the requested resource does not exist
/io:
  displayName: Inputs/Outputs View
  get:
    description: Get a view on all Inputs and Outputs
    responses:
      200:
        body:
          example: !include ../examples/io-get-200.json
          type: !include schemas/io-response-schema.json