oic.wk.rd.raml

#%RAML 0.8
#RAML for Resource Directory
title: Resource Directory
version: v1-20160622
documentation:

  - title: OCF Copyright
    content: Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights reserved.
  - title: OCF License
    content: !include LICENSE.md
  - title: OCF Disclaimer
    content: !include DISCLAIMER.md

schemas:
  # rdSelection represents the payload of GET response.
  # rdPublish represents the payload in POST request.
-  rdSelection: !include schemas/oic.rd.selection-schema.json
-  rdPublish: !include schemas/oic.rd.publish-schema.json

traits:
- rdgetinterface:
    queryParameters:
      if:
        description: |
          Interface is optional since there is only one interface supported for the Resource Type
          Both for RD selection and for publish.
          Example:  GET /oic/rd?if=oic.if.baseline
        enum: [ "oic.if.baseline" ]

- rdpostinterface:
    queryParameters:
      if:
        description: |
          Interface is optional since there is only one interface supported for the Resource Type
          Both for RD selection and for publish.
          Example:  POST /oic/rd?if=oic.if.baseline
        enum: ["oic.if.baseline"]

/oic/rd:
  displayName: Resource directory resource
  description: |
    Resource to be exposed by any Device that can act as a Resource Directory.
    1) Provides selector criteria (e.g., integer) with GET request
    2) Publish a Link in /oic/res with POST request

  get:
    is: [ rdgetinterface ]
    description: |
      Get the attributes of the Resource Directory for selection purposes.

    responses:
      200:
        description: |
          Respond with the selector criteria - either the set of attributes or the bias factor
        body:
          application/json:
            schema: rdSelection
            example: |
              {
                "rt": ["oic.wk.rd"],
                "if": ["oic.if.baseline"],
                "sel": 50
              }

  post:
    is: [ rdpostinterface ]
    description: |
      Publish the resource information for the first time in /oic/res. Updates to existing entries are not allowed.
      Appropriates parts of the information, i.e., Links of the published Resources will be discovered through /oic/res.
      1) When a Device first publishes a Link, the request payload to RD may include the Links without an "ins" Parameter.
      2) Upon granting the request, the RD assigns a unique instance value identifying the Link among all the Links it advertises
         and sends back the instance value in the "ins" Parameter in the Link to the publishing Device.
    body:
      application/json:
        schema: rdPublish
        example: |
              {
                "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                "links": [
                  {
                    "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                    "href":   "/myLightSwitch",
                    "rt":     ["oic.r.switch.binary"],
                    "if":     ["oic.if.a", "oic.if.baseline"],
                    "p":      {"bm": 3},
                    "eps": [
                        {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2},
                        {"ep": "coaps://[2001:db8:a::b1d6]:1122"},
                        {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3}
                    ]
                  },
                  {
                    "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                    "href":   "/myLightBrightness",
                    "rt":     ["oic.r.brightness"],
                    "if":     ["oic.if.a", "oic.if.baseline"],
                    "p":      {"bm": 3},
                    "eps": [
                        {"ep": "coaps://[[2001:db8:a::123]:2222"}
                    ]
                  }
                ],
                "ttl": 600
              }
    responses:
      200:
        description: |
          Respond with the same schema as publish with the additional "ins" Parameter in the Link.
        body:
          application/json:
            schema: rdPublish
            example: |
              {
                "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                "links": [
                  {
                    "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                    "href":   "/myLightSwitch",
                    "rt":     ["oic.r.switch.binary"],
                    "if":     ["oic.if.a", "oic.if.baseline"],
                    "p":      {"bm": 3},
                    "eps": [
                        {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2},
                        {"ep": "coaps://[2001:db8:a::b1d6]:1122"},
                        {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3}
                    ],
                    "ins":    11235
                  },
                  {
                    "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
                    "href":   "/myLightBrightness",
                    "rt":     ["oic.r.brightness"],
                    "if":     ["oic.if.a", "oic.if.baseline"],
                    "p":      {"bm": 3},
                    "eps": [
                        {"ep": "coaps://[2001:db8:a::123]:2222"}
                    ],
                    "ins":    112358
                  }
                ],
                "ttl": 600
              }

# The discovery through the /oic/res of the resource directory is the same
# as specified in 11.3.6.4.1 /oic/res and retrieving of the resources