openapi-spec.yml

openapi: 3.0.0

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

info:
  version: "1.0.0-beta.22"
  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: things
    description: Registration API
  - name: search
    description: Search API
  - name: events
    description: Notification API
  - name: validation
    description: Validation API
  - name: td
    description: Registration API (deprecated)

paths:
  /td:
    get:
      deprecated: true
      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
          deprecated: true
          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
          deprecated: true
          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'
    post:
      deprecated: true
      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/RespValidationBadRequest'
        '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:
      deprecated: true
      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:
        '201':
          description: A new Thing Description is created
        '204':
          description: Thing Description updated successfully
        '400':
          $ref: '#/components/responses/RespValidationBadRequest'
        '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:
      deprecated: true
      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:
        '204':
          description: Thing Description patched successfully
        '400':
          $ref: '#/components/responses/RespValidationBadRequest'
        '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:
      deprecated: true
      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:
      deprecated: true
      tags:
        - td
      summary: Deletes the Thing Description
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful response
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '404':
          $ref: '#/components/responses/RespNotfound'
        '500':
          $ref: '#/components/responses/RespInternalServerError'

  /things:
    get:
      tags:
        - things
      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
          deprecated: true
          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
          deprecated: true
          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'
    post:
      tags:
        - things
      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/RespValidationBadRequest'
        '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
  /things/{id}:
    put:
      tags:
        - things
      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:
        '201':
          description: A new Thing Description is created
        '204':
          description: Thing Description updated successfully
        '400':
          $ref: '#/components/responses/RespValidationBadRequest'
        '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:
        - things
      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:
        '204':
          description: Thing Description patched successfully
        '400':
          $ref: '#/components/responses/RespValidationBadRequest'
        '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:
        - things
      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:
        - things
      summary: Deletes the Thing Description
      parameters:
        - name: id
          in: path
          description: ID of the Thing Description
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful response
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '404':
          $ref: '#/components/responses/RespNotfound'
        '500':
          $ref: '#/components/responses/RespInternalServerError'

  /search/jsonpath:
    get:
      tags:
        - search
      summary: Query TDs with JSONPath expression
      description: The query languages, described [here](https://github.com/linksmart/thing-directory/wiki/Query-Language), can be used to filter results and select parts of Thing Descriptions.
      parameters:
        - name: query
          in: query
          description: JSONPath expression for fetching specific items. E.g. `$[?(@.title=='Kitchen Lamp')].properties`
          required: true
          schema:
            type: string
          # example: $[?(@.title=='Kitchen Lamp')].properties
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
                    - type: integer
                    - type: boolean
                    - type: array
                    - type: object
              # 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'
  /search/xpath:
    get:
      tags:
        - search
      summary: Query TDs with XPath expression
      description: The query languages, described [here](https://github.com/linksmart/thing-directory/wiki/Query-Language), can be used to filter results and select parts of Thing Descriptions.
      parameters:
        - name: query
          in: query
          description: xPath 3.0 expression for fetching specific items. E.g. `//*[title='Kitchen Lamp']/properties`
          required: true
          schema:
            type: string
          # example: //*[title='Kitchen Lamp']/properties
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
                    - type: integer
                    - type: boolean
                    - type: array
                    - type: object
              # 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'


  /events:
    get:
      tags:
        - events
      summary: Subscribe to all events
      description: This API uses the [Server-Sent Events (SSE)](https://www.w3.org/TR/eventsource/) protocol.
      parameters:
        - name: diff
          in: query
          description: Include changed TD attributes inside events payload
          required: false
          schema:
            type: boolean
      responses:
        '200':
          $ref: '#/components/responses/RespEventStream'
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '500':
          $ref: '#/components/responses/RespInternalServerError'
  /events/{type}:
    get:
      tags:
        - events
      summary: Subscribe to specific events
      description: This API uses the [Server-Sent Events (SSE)](https://www.w3.org/TR/eventsource/) protocol.
      parameters:
        - name: type
          in: path
          description: Event type
          required: true
          schema:
            type: string
            enum:
              - create
              - update
              - delete
        - name: diff
          in: query
          description: Include changed TD attributes inside events payload
          required: false
          schema:
            type: boolean
      responses:
        '200':
          $ref: '#/components/responses/RespEventStream'
        '400':
          $ref: '#/components/responses/RespBadRequest'
        '401':
          $ref: '#/components/responses/RespUnauthorized'
        '403':
          $ref: '#/components/responses/RespForbidden'
        '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/ProblemDetails'
    RespValidationBadRequest:
      description: Bad Request (e.g. validation error)
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - $ref: '#/components/schemas/ValidationError'
    ValidationErrorResponse:
      description: Invalid Thing Description
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    RespUnauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    RespForbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    RespNotfound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    RespConflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    RespInternalServerError:
      description: Internal Server Error
      content:
        application/ld+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    RespEventStream:
      description: Events stream
      content:
        text/event-stream:
          schema:
            type: array
            format: chunked
            items:
              type: object
              format: text
              required:
                - id
                - event
                - data
              properties:
                id:
                  type: integer
                  description: event id
                event:
                  type: string
                  description: event type
                data:
                  type: object
                  format: json
                  required:
                    - id
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    ProblemDetails:
      description: RFC7807 Problem Details (https://tools.ietf.org/html/rfc7807)
      properties:
        #        type:
        #          type: string
        #          description: A URI reference that identifies the problem type.
        status:
          type: integer
          format: int32
          description: The HTTP status code.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.\
    ValidationError:
      description: Thing Description validation error
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
        - type: object
          properties:
            validationErrors:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  description:
                    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
        }