Merge pull request #911 from bosch-io/doc/cloudevents-openapi

[#903] provide OpenAPI documentation for /cloudevents on API 2

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -25,6 +25,8 @@ tags:
     description: Find every thing
   - name: Messages
     description: Talk with your things
+  - name: CloudEvents
+    description: Process CloudEvents in Ditto
 security:
   - basicAuth: []
   - bearerAuth: []
@@ -4858,6 +4860,157 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdvancedError'
+  /cloudevents:
+    post:
+      summary: Processes a CloudEvent sent in Ditto Protocol
+      description: |-
+        Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md)
+        in [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html).
+
+        The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination.
+
+        Find more documentation on that [here](https://www.eclipse.org/ditto/httpapi-protocol-bindings-cloudevents.html).
+      tags:
+        - CloudEvents
+      parameters:
+        - in: header
+          name: ce-specversion
+          description: The CloudEvents "specversion".
+          schema:
+            type: string
+            example: '1.0'
+          required: true
+        - in: header
+          name: ce-type
+          description: The CloudEvents event "type".
+          schema:
+            type: string
+            example: com.example.someevent
+          required: true
+        - in: header
+          name: ce-source
+          description: The CloudEvents event "source".
+          schema:
+            type: string
+            example: /mycontext
+          required: true
+        - in: header
+          name: ce-id
+          description: The CloudEvents event "id".
+          schema:
+            type: string
+            example: 1234-1234-1234
+          required: true
+        - in: header
+          name: ce-time
+          description: The CloudEvents event "time".
+          schema:
+            type: string
+            format: date-time
+            example: '2020-12-31T23:59:59Z'
+          required: true
+        - in: header
+          name: ce-dataschema
+          description: 'The CloudEvents event "dataschema". If provided, this must start with `ditto:`.'
+          schema:
+            type: string
+          required: false
+      responses:
+        '202':
+          description: 'The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence.'
+        '400':
+          description: |-
+            The request could not be completed. Possible reasons:
+              * the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request
+              * the payload was missing from the CloudEvent
+              * the [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) message could not be parsed or was missing a required field
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '401':
+          description: The request could not be completed due to missing authentication.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '403':
+          description: |-
+            The request could not be completed. Possible reasons:
+              * the caller has insufficient permissions.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '404':
+          description: |-
+            The request could not be completed. Possible reasons:
+              * the referenced thing does not exist.
+              * the caller has insufficient permissions to perform the contained Ditto Protocol command.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '408':
+          description: The request could not be completed due to timeout.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+        '415':
+          description: The `Content-Type` of the request was not supported.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdvancedError'
+      requestBody:
+        content:
+          application/vnd.eclipse.ditto+json:
+            schema:
+              type: object
+              properties:
+                topic:
+                  type: string
+                  description: |-
+                    Contains information about the contents of the payload:
+                    * the affected Thing (namespace and Thing ID)
+                    * the type of operation (command/event, create/retrieve/modify/delete)
+                  example: org.eclipse.ditto/thing-1/things/twin/commands/modify
+                headers:
+                  type: object
+                  description: Additional headers.
+                  properties:
+                    correlation-id:
+                      type: string
+                      description: |-
+                        The correlation-id header is used for linking one message with another.
+                        It typically links a reply message with its requesting message.
+                  example:
+                    correlation-id: 1234-4321-1234
+                path:
+                  type: string
+                  description: References the part of a Thing which is affected by this message.
+                  example: /features/location/properties/longitude
+                value:
+                  oneOf:
+                    - type: object
+                    - type: string
+                    - type: number
+                    - type: array
+                    - type: boolean
+                  description: The `value` field contains the actual payload e.g. a sensor value.
+              required:
+                - topic
+                - path
+            example:
+              topic: org.eclipse.ditto/thing-1/things/twin/commands/modify
+              path: /
+              value:
+                attributes:
+                  foo: 42
+        description: |-
+          The [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) payload defining which
+          command to process.
 components:
   responses:
     EntityTooLarge:

documentation/src/main/resources/openapi/sources/api-2-index.yml

@@ -37,6 +37,8 @@ tags:
     description: Find every thing
   - name: Messages
     description: Talk with your things
+  - name: CloudEvents
+    description: Process CloudEvents in Ditto
 
 security:
   #  - Google:
@@ -126,6 +128,12 @@ paths:
   /search/things/count:
     $ref: "./paths/search/things-count.yml"
 
+  ###
+  ### CloudEvents
+  ###
+  '/cloudevents':
+    $ref: "./paths/cloudevents/cloudevents.yml"
+
 components:
 
   responses:

documentation/src/main/resources/openapi/sources/paths/cloudevents/cloudevents.yml

@@ -0,0 +1,115 @@
+# Copyright (c) 2020 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0
+#
+# SPDX-License-Identifier: EPL-2.0
+post:
+  summary: Processes a CloudEvent sent in Ditto Protocol
+  description: |-
+    Provides an endpoint accepting [CloudEvents via its HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md)
+    in [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html).
+
+    The endpoint can also directly be configured as a [Knative eventing](https://knative.dev/docs/eventing/) destination.
+
+    Find more documentation on that [here](https://www.eclipse.org/ditto/httpapi-protocol-bindings-cloudevents.html).
+  tags:
+    - CloudEvents
+  parameters:
+    - in: header
+      name: ce-specversion
+      description: The CloudEvents "specversion".
+      schema:
+        type: string
+        example: "1.0"
+      required: true
+    - in: header
+      name: ce-type
+      description: The CloudEvents event "type".
+      schema:
+        type: string
+        example: "com.example.someevent"
+      required: true
+    - in: header
+      name: ce-source
+      description: The CloudEvents event "source".
+      schema:
+        type: string
+        example: "/mycontext"
+      required: true
+    - in: header
+      name: ce-id
+      description: The CloudEvents event "id".
+      schema:
+        type: string
+        example: "1234-1234-1234"
+      required: true
+    - in: header
+      name: ce-time
+      description: The CloudEvents event "time".
+      schema:
+        type: string
+        format: date-time
+        example: "2020-12-31T23:59:59Z"
+      required: true
+    - in: header
+      name: ce-dataschema
+      description: The CloudEvents event "dataschema". If provided, this must start with `ditto:`.
+      schema:
+        type: string
+      required: false
+  responses:
+    '202':
+      description: |-
+        The Ditto Protocol CloudEvent was successfully parsed, the authentication was valid and also reached the persistence.
+    '400':
+      description: |-
+        The request could not be completed. Possible reasons:
+          * the CloudEvent could not be parsed as some mandatory CloudEvent headers were missing from the request
+          * the payload was missing from the CloudEvent
+          * the [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) message could not be parsed or was missing a required field
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+    '401':
+      description: The request could not be completed due to missing authentication.
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+    '403':
+      description: |-
+        The request could not be completed. Possible reasons:
+          * the caller has insufficient permissions.
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+    '404':
+      description: |-
+        The request could not be completed. Possible reasons:
+          * the referenced thing does not exist.
+          * the caller has insufficient permissions to perform the contained Ditto Protocol command.
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+    '408':
+      description: The request could not be completed due to timeout.
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+    '415':
+      description: The `Content-Type` of the request was not supported.
+      content:
+        application/json:
+          schema:
+            $ref: '../../schemas/advancedError.yml'
+  requestBody:
+    $ref: '../../requests/dittoProtocol.yml'

documentation/src/main/resources/openapi/sources/requests/dittoProtocol.yml

@@ -0,0 +1,60 @@
+# Copyright (c) 2020 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0
+#
+# SPDX-License-Identifier: EPL-2.0
+content:
+  application/vnd.eclipse.ditto+json:
+    schema:
+      type: object
+      properties:
+        topic:
+          type: string
+          description: |-
+            Contains information about the contents of the payload:
+            * the affected Thing (namespace and Thing ID)
+            * the type of operation (command/event, create/retrieve/modify/delete)
+          example: "org.eclipse.ditto/thing-1/things/twin/commands/modify"
+        headers:
+          type: object
+          description: Additional headers.
+          properties:
+            correlation-id:
+              type: string
+              description: |-
+                The correlation-id header is used for linking one message with another.
+                It typically links a reply message with its requesting message.
+          example:
+            correlation-id: "1234-4321-1234"
+        path:
+          type: string
+          description: References the part of a Thing which is affected by this message.
+          example: "/features/location/properties/longitude"
+        value:
+          oneOf:
+            - type: "object"
+            - type: "string"
+            - type: "number"
+            - type: "array"
+            - type: "boolean"
+          description: The `value` field contains the actual payload e.g. a sensor value.
+      required:
+        - topic
+        - path
+    example: {
+      "topic": "org.eclipse.ditto/thing-1/things/twin/commands/modify",
+      "path": "/",
+      "value": {
+        "attributes": {
+          "foo": 42
+        }
+      }
+    }
+description: |-
+  The [Ditto Protocol JSON](https://www.eclipse.org/ditto/protocol-specification.html) payload defining which
+  command to process.

model/base/src/main/java/org/eclipse/ditto/model/base/exceptions/CloudEventMissingPayloadException.java

@@ -37,8 +37,8 @@ public final class CloudEventMissingPayloadException extends DittoRuntimeExcepti
       */
      public static final String ERROR_CODE = "cloudevent.payload.missing";
 
-     private static final String DEFAULT_MESSAGE = "The cloud event's payload is missing.";
-     private static final String DEFAULT_DESCRIPTION = "Ensure to provide payload in the cloud event.";
+     private static final String DEFAULT_MESSAGE = "The Cloud Event's payload is missing.";
+     private static final String DEFAULT_DESCRIPTION = "Ensure to provide payload in the Cloud Event.";
 
      private static final HttpStatusCode STATUS_CODE = HttpStatusCode.BAD_REQUEST;
 

model/base/src/main/java/org/eclipse/ditto/model/base/exceptions/CloudEventNotParsableException.java

@@ -38,10 +38,10 @@ public final class CloudEventNotParsableException extends DittoRuntimeException
       */
      public static final String ERROR_CODE = "cloudevent.unparsable";
 
-     private static final String DEFAULT_MESSAGE = "The event could not be parsed.";
-     private static final String MESSAGE_PATTERN = "The system was unable to parse the event: {0}";
-     private static final String DESCRIPTION =
-             "Ensure that the event is being transmitted according to the Cloud Events HTTP binding specification v1.0.";
+     private static final String DEFAULT_MESSAGE = "Unable to parse as Cloud Event.";
+     private static final String MESSAGE_PATTERN = "Unable to parse as Cloud Event because of: <{0}>";
+     private static final String DESCRIPTION = "Ensure that the event is being transmitted according to the " +
+             "Cloud Events HTTP binding specification v1.0 and that all mandatory headers were set.";
      private static final URI DEFAULT_URI =
              URI.create("https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md");