Working samples for adapting OpenAPI/AsyncAPI for CoRE

coreapi-async.yaml

asyncapi: 2.0.0
info: 
  title: Example CoREAPI based on AsyncAPI
  version: 0.0.0

coreapi-oas.yaml

openapi: 3.0.3
info:
  title: Example CoREAPI based on OpenAPI
  version: 0.0.0
tags:

servers:
  - url: '{scheme}://example.com'
    variables:
      scheme:
        enum:
          - 'coap'
          - 'coaps'
          - 'coap+tcp'
          - 'coaps+tcp'
        default: 'coaps'
paths:
  /temperature:
    get:
      operationId: getTemp
      summary: Get temperature
      parameters:
        - name: type
          in: header #pretend header is option
          description: 'Type of message'
          schema:
            type: string
            enum: [confirmable, non-confirmable]
      x-option:
        - name: token
          description: 'Token used to match response with request'
          required: false
          schema:
            type: integer
            format: byte
        - name: observe
          description: 'Register/deregister request to be notified about Temperature changes'
          required: false
          type: boolean
      responses:
        'x-2.05': # or just use 205?
          description: >-
            Temperature value found
          content:
            charset=utf-8:
              schema:
                $ref: '#/components/schemas/Temp'
              examples:
                recording: '22.3 C'
          options:
            type:
              description: 'Type of message'
              type: string
              enum: [acknowledgement, reset]
    /.well-known/core:
      get:
        address: # not a valid RFC 6690, just to demo web linking from OAS
          operationId: getUserAddress
          parameters:
            userId: $request.path.id
    x-fetch:
    x-patch:
    x-ipatch:
webhooks: # treat webhooks like an Observe notification. Or define x-notifcations?
  newTempReading:
    get:
      requestBody:
        description: >-
          Temperature value found
        content:
          charset=utf-8:
            schema:
              $ref: '#/components/schemas/Temp'
            examples:
              recording: '22.3 C'
      responses:
        'x-2.05': # or just use 205?
        description: >-
          Temperature value found
components:
  schemas:
    Temp:
      required:
        - recording
      properties:
        recording:
          type: string
          format: utf-8

coreapi-pseudo.yaml

coreapi: 0.0.0 #!OAS
servers:
  - url: '{scheme}://example.com'
    variables:
      scheme:
        enum:
          - 'coap'
          - 'coaps'
          - 'coap+tcp'
          - 'coaps+tcp'
        default: 'coaps'
info:
  title: Psuedo CoreAPI specification
  version: 0.0.0
paths:
  /temperature:
    get:
      operationId: getTemp
      summary: Get temperature
      parameters:
        - name: type
          in: options #!OAS
          description: 'Type of message'
          schema:
            type: string
            enum: [confirmable, non-confirmable]
        - name: token
          in: options
          description: 'Token used to match response with request'
          required: false
          schema:
            type: integer
            format: byte #!OAS
      responses:
        '2.05':
          description: >-
            Temperature value found
          content:
            charset=utf-8:
              schema:
                $ref: '#/components/schema/Temp'
              examples:
                recording: '22.3 C'
          options: #!OAS
            type:
              description: 'Type of message'
              type: string
              enum: [acknowledgement, reset]
    post:
    delete:
    put:
    fetch: #!OAS
    patch: #!OAS
    ipatch: #!OAS
observables: #!OAS, but similar to webhooks.
  # Arguably registration/re-registration could happen in Paths & this renamed to Notifications
  # AsyncAPI "Channels" might be a better fit
  paths:
    /temperature/critical:
      get:
        operationalId: observeCriticalTemp
        summary: get notified when temperature meets a threshold
        parameters:
          - name: observe
            in: options #!OAS
            description: Register to deregister observe request
            required: true
            type: boolean
  notifications:
groups: #!OAS. May also be a better fit for AsyncAPI
discovery: #!OAS
proxies: #!OAS
components:
  schema:
    Temp:
      required:
        - recording
      properties:
        recording:
          type: string
          format: utf-8

Have you made any further efforts along these lines? We find ourselves focused on this issue for CoAP APIs.

I know CoAP already has resource discovery but that doesn't give an interface description like OpenAPI or AsyncAPI does.

The CoRE Link Format has the "if" attribute which could link to a yaml file which specifies the API interface. In RFC6690, they show the example of the CoRE Link Format.

REQ: GET /.well-known/core

RES: 2.05 Content
</sensors/temp>;if="sensor",
</sensors/light>;if="sensor"

The "sensor" values would presumably have some interface meaning to the developers but is not documented. Instead, we could do the following:

REQ: GET /.well-known/core

RES: 2.05 Content
</sensors/temp>;if="/sensors.yaml#temp",
</sensors/light>;if="/sensors.yaml#light"

Which would presumably line up with a path description in the OpenAPI file. I'm not sure if there's a way to reference paths within a specification file like I've done.

Ping @beriberikix

Hi @jacobeverist! I haven't touched this in a long time 😅. We're still very much interested in seeing this exist but have other priorities at the moment. Are you interested in collaborating? I'd certainly welcome someone to drive this and provide input!

@beriberikix what is your use case for this type of thing? Sorry, I don't quite know what work you do and what your priorities are. You're just the only person on the web I've found that's made more than a half-hearted effort on CoAP API descriptions.

We're interested in using this for plug-in-play functionality of devices on small spacecraft, as well as communication between small spacecraft, and in-the-loop simulation capabilities. The development and launching of cubesat size spacecraft needs to be agile and fast, unlike the current traditional development of large satellites which takes years from design-to-launch. We're trying to port the RESTful, fail-early fail-often, development style that the internet has adopted to the space industry. So CoAP would be running on a variety of physical layers such 1553, UART, ethernet, radio, etc, not just running on the internet. These would definitely be constrained resources.

Furthermore, we're trying to graft autonomous capabilities onto existing systems, and this kind of interface description would seem to be important for interacting with the systems that are already there.

Have you seen Hydra? This effort seems to cover things that OpenAPI and AsyncAPI do not, which involves semantic relations, and affordances with each resource. I've just started looking at it, but it can essentially instruct a machine-client how to use and interact with the resource. There are already some semantic relationship information in the CoRE Link Format, but information on how-to-use the resource seems to be out-of-band.

I genuinely don't know how important semantics and affordances would be and whether it would add significant overhead to constrained resources. I'm usually skeptical of semantic-web-like functionality due to the enormous technical investment and the general community acceptance required. However, Hydra seems to have lots of functional software libraries out there, so there may be something to it.

How do you envision collaboration? Can you recommend a software stack to act as a testbed for this kind of thing that makes the mechanics and the value easy to understand to new people?