openapi-spec.yml

openapi: 3.0.3

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

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

tags:
  - name: things
    description: Things API
  - name: search
    description: Search API
  - name: events
    description: Notification API

paths:
  /things:
    get:
      tags:
        - things
      summary: Retrieves the list of Thing Descriptions
      parameters:
        - name: offset
          in: query
          description: Offset number in the pagination
          required: false
          schema:
            type: number
            format: integer
            default: 0
        - name: limit
          in: query
          description: Number of entries per page. When not set, all entries are returned incrementally.
          required: false
          schema:
            type: number
            format: integer
      responses:
        '200':
          description: Successful response
          content:
            application/ld+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ThingDescription'
        '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/td+json:
            schema:
              $ref: '#/components/schemas/ThingDescription'
            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/td+json:
            schema:
              $ref: '#/components/schemas/ThingDescription'
            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/td+json:
              schema:
                $ref: '#/components/schemas/ThingDescription'
              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/tinyiot/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'

  /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'

security:
  - BasicAuth: []
  - BearerAuth: []

components:
  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:
    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:
      #type: object
      $ref: 'https://raw.githubusercontent.com/w3c/wot-thing-description/main/validation/td-json-schema-validation.json'
     
    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"}
          }
        }