openapi-spec.yml

openapi: 3.0.0

#servers:
#  - url: http://localhost:8081

info:
  version: "1.0.0-beta.18"
  title: LinkSmart Thing Directory
  description: API documetnation of the [LinkSmart Thing Directory](https://github.com/linksmart/thing-directory)
  license:
    name: Apache 2.0
    url: https://github.com/linksmart/thing-directory/blob/master/LICENSE

tags:
  - name: td
    description: Thing Directory API
  - name: validation
    description: Validation API

paths:
  /td:
    get:
      tags:
        - td
      summary: Retrieves paginated list of Thing Descriptions
      description: The query languages, described [here](https://github.com/linksmart/thing-directory/wiki/Query-Language), can be used to filter results and fetch parts of Thing Descriptions.
      parameters:
        - $ref: '#/components/parameters/ParamPage'
        - $ref: '#/components/parameters/ParamPerPage'
        - name: jsonpath
          in: query
          description: JSONPath expression for fetching specific items. E.g. `$[?(@.title=='Kitchen Lamp')].properties`
          required: false
          schema:
            type: string
          # example: $[?(@.title=='Kitchen Lamp')].properties
        - name: xpath
          in: query
          description: xPath 3.0 expression for fetching specific items. E.g. `//*[title='Kitchen Lamp']/properties`
          required: false
          schema:
            type: string
          # example: //*[title='Kitchen Lamp']/properties
      responses:
        '200':
          description: Successful response
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/ThingDescriptionPage'
              examples:
                ThingDescriptionList:
                  $ref: '#/components/examples/ThingDescriptionList'
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
  /td/:
    post:
      tags:
        - td
      summary: Creates new Thing Description with system-generated ID
      description: |
        This is to create a TD and receive a unique system-generated `id` in response.<br>
        The server rejects the request if there is an `id` in the body.<br>
        For creating a TD with user-defined `id`, use the `PUT` method.
      responses:
        '201':
          description: Created successfully
          headers:
            Location:
              description: Path to the newly created Thing Description
              schema:
                type: string
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
      requestBody:
        content:
          application/ld+json:
            schema:
              type: object
            examples:
              ThingDescription:
                $ref: '#/components/examples/ThingDescriptionWithoutID'

        description: Thing Description to be created
        required: true
  /td/{id}:
    put:
      tags:
        - td
      summary: Creates a new Thing Description with the provided ID, or updates an existing one
      description: |
        The `id` in the path is the resource id and must match the one in Thing Description.<br>
        For creating a TD without user-defined `id`, use the `POST` method.
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          example: "urn:example:1234"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thing Description updated successfully
        '201':
          description: A new Thing Description is created
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '409':
          $ref: '#/components/responses/RespConflict'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
      requestBody:
        content:
          application/ld+json:
            schema:
              type: object
            examples:
              ThingDescription:
                $ref: '#/components/examples/ThingDescriptionWithID'
        description: The Thing Description object
        required: true
    patch:
      tags:
        - td
      summary: Patch a Thing Description
      description: The patch document must be based on RFC7396 JSON Merge Patch
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          example: "urn:example:1234"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thing Description patched successfully
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '409':
          $ref: '#/components/responses/RespConflict'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              type: object
            examples:
              ThingDescription:
                $ref: '#/components/examples/ThingDescriptionWithID'
        description: The Thing Description object
        required: true
    get:
      tags:
        - td
      summary: Retrieves a Thing Description
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          example: "urn:example:1234"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/ld+json:
              schema:
                type: object
              examples:
                response:
                  $ref: '#/components/examples/ThingDescriptionWithID'
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '404':
          $ref: '#/components/responses/RespNotfound'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
    delete:
      tags:
        - td
      summary: Deletes the Thing Description
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '404':
          $ref: '#/components/responses/RespNotfound'
        '500':
          $ref: '#/components/responses/RespInternalServerError'

  /validation:
    get:
      tags:
        - validation
      summary: Retrieves the validation result for a given Thing Description
      description: |
        The Thing Description should be provided as JSON in the request body.<br>
        Note: This is currently not supported using Swagger UI.
      responses:
        '200':
          description: Validation Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
      # wait for openapi 3.1.0 which brings back support for requetsBody in GET
      # requestBody:
      #   content:
      #     application/ld+json:
      #       schema:
      #         type: object
      #       examples:
      #         ThingDescription:
      #           $ref: '#/components/examples/ThingDescription'
security:
  - BasicAuth: []
  - BearerAuth: []

components:
  parameters:
    ParamPage:
      name: page
      in: query
      description: Page number in the pagination
      required: false
      schema:
        type: number
        format: integer
    ParamPerPage:
      name: per_page
      in: query
      description: Number of entries per page
      required: false
      schema:
        type: number
        format: integer
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    RespBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RespUnauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RespForbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RespNotfound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RespConflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RespInternalServerError:
      description: Internal Server Error
      content:
        application/ld+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    ThingDescription:
      description: WoT Thing Description
      type: object
    ThingDescriptionPage:
      type: object
      properties:
        '@context':
          format: url
        '@type':
          format: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ThingDescription'
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer
    ValidationResult:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: string
  examples:
    ThingDescriptionWithoutID:
      summary: Example Thing Description
      value:
        {
          "@context": "https://www.w3.org/2019/wot/td/v1",
          "title": "ExampleSensor",
          "properties": {
            "status": {
              "forms": [
                {
                  "op": ["readproperty"],
                  "href": "https://example.com/status",
                  "contentType": "text/html"
                }
              ]
            }
          },
          "security": ["nosec_sc"],
          "securityDefinitions": {"nosec_sc":{"scheme":"nosec"}
          }
        }
    ThingDescriptionWithID:
      summary: Example Thing Description
      value:
        {
          "@context": "https://www.w3.org/2019/wot/td/v1",
          "id": "urn:example:1234",
          "title": "ExampleSensor",
          "properties": {
            "status": {
              "forms": [
                {
                  "op": ["readproperty"],
                  "href": "https://example.com/status",
                  "contentType": "text/html"
                }
              ]
            }
          },
          "security": ["nosec_sc"],
          "securityDefinitions": {"nosec_sc":{"scheme":"nosec"}
          }
        }
    ThingDescriptionList:
      summary: Example Paginated Thing Descriptions
      value:
        {
          "@context": "https://linksmart.eu/thing-directory/context.jsonld",
          "@type": "Catalog",
          "items":[
            {
              "@context": "https://www.w3.org/2019/wot/td/v1",
              "id": "urn:example:1234",
              "title": "ExampleSensor",
              "properties": {
                "status": {
                  "forms": [
                    {
                      "op": ["readproperty"],
                      "href": "https://example.com/status",
                      "contentType": "text/html"
                    }
                  ]
                }
              },
              "security": ["nosec_sc"],
              "securityDefinitions": {"nosec_sc":{"scheme":"nosec"}
              }
            }
          ],
          "page": 1,
          "perPage": 100,
          "total": 1
        }