Merge branch 'master' of https://github.com/opengeospatial/developer-website

Author: doublebyte1

api/connectedsystems/api/batch-mode.adoc

@@ -0,0 +1,293 @@
+=== Batch Mode
+
+This standard defines a simple batch protocol so that large numbers of resources can be added, replaced and deleted in a more efficient manner.
+
+This section provides general requirements for the batch mode as well as some request/response payload requirements for the batch operations. For BATCH CREATE and BATCH REPLACE operations, each encoding requirements class must define the payload to use for batching resource representations.
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-mode
+
+The server SHALL support batch mode on all resource collection endpoints that support create, replace and delete operations on resources.
+====
+
+
+==== Requirements common to all batch operations
+
+A fully successful execution of a batch operation is always reported as a response with HTTP status code 200 and includes a reponse body.
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-mode-success
+
+conditions:: No error occurs during individual resource operations.
+
+part:: The server SHALL respond with an HTTP status code 200.
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+====
+
+It is up to the server implementation to reject the entire batch request if some of the operations fail, or to allow partial processing. If the server rejects the entire request, it must indicate this with a single error status code, and must also guarantee that any applied changes are rolled back (processed as an atomic transaction).
+
+In all cases, the response body provides detailed status for each individual resource operation.
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-mode-partial
+
+conditions::
+  - Some errors occur during individual resource operations.
+  - The server allows for partial processing.
+
+part:: The server SHALL respond with an HTTP status code 200.
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+====
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-mode-atomic
+
+conditions::
+  - Some errors occur during individual resource operations.
+  - The server rejects entire request.
+
+part:: The server SHALL respond with an HTTP status code greater or equal to 400 (i.e. either a client error or server error status code).
+
+part:: All applied changes SHALL be rolled back by the server.
+
+part:: The server MAY include a response body, in which case the response body SHALL be valid according to the JSON schema {batch-response-schema-ref}.
+====
+
+
+==== Batch Create
+
+===== Operation
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-create-op
+
+The BATCH CREATE operation SHALL be implemented as an HTTP POST request on the resource collection where the resources are to be added.
+====
+
+===== Request Body
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-create-request
+
+part:: The body of the POST request SHALL contain the representations of the new resources to be added to the collection.
+
+part:: Each resource representation SHALL include an `id` that will be used to identify the resource in the batch response. The server MAY generate a new `id` for the resource.
+
+part:: The `Content-Type` header SHALL be set to a media type that defines a proper batching format.
+====
+
+===== Response
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-create-response
+
+conditions:: The request is successful or partially successful
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+
+part:: For each resource included in the request, the response SHALL contain exactly one JSON object with the following data:
+  - The `id` attribute SHALL contain the value of the `id` of the resource as provided in the request  (not the id eventually generated by the server).
+  - The `status` attribute SHALL contain the HTTP status code that would have been returned if the resource had been added individually using a CREATE operation.
+  - The `location` attribute SHALL contain the URL of the newly added resource if successful
+  - The `error` attribute MAY contain an error message describing why the operation failed for this resource.
+====
+
+
+==== Batch Replace
+
+===== Operation
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-replace-op
+
+The BATCH REPLACE operation SHALL be implemented as an HTTP POST request on the sub-resource `/replace` of the resource collection that contains the resources to be replaced (e.g. `{api_root}/systems/replace`).
+====
+
+===== Request Body
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-replace-request
+
+part:: The body of the POST request SHALL contain the new representations of the resources to be replaced in the collection.
+
+part:: Each resource representation in the list SHALL contain the `id` of an existing resource to be replaced.
+
+part:: The `Content-Type` header SHALL be set to a media type that defines a proper batching format.
+====
+
+===== Response
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-replace-response
+
+conditions:: The request is successful or partially successful
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+
+part:: For each resource included in the request, the response SHALL contain exactly one JSON object with the following data:
+  - The `id` attribute SHALL contain the value of the `id` of the resource as provided in the request.
+  - The `status` attribute SHALL contain the HTTP status code that would have been returned if the resource had been replaced individually using a REPLACE operation.
+  - The `error` attribute MAY contain an error message describing why the operation failed for this resource.
+====
+
+
+==== Batch Delete
+
+===== Operation
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-delete-op
+
+The server SHALL implement the BATCH DELETE request by accepting a POST request on the sub-resource `/delete` on the resource collection that contains the resources to be deleted (e.g. `{api_root}/systems/delete`).
+====
+
+===== Request Body
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-delete-request
+
+part:: The `Content-Type` header SHALL be set to `application/json`.
+part:: The body of the request SHALL be valid against the JSON schema {batch-delete-schema}.
+====
+
+===== Response
+
+The server must generate the response as specified in the "Error Handling" section.
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/create-replace-delete/batch-delete-response
+
+conditions:: The request is successful or partially successful
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+
+part:: For each resource included in the request, the response SHALL contain exactly one JSON object with the following data:
+  - The `id` attribute SHALL contain the value of the `id` of the resource as provided in the request.
+  - The `status` attribute SHALL contain the HTTP status code that would have been returned if the resource had been deleted individually using a DELETE operation.
+  - The `error` attribute MAY contain an error message describing why the operation failed for this resource.
+====
+
+
+==== Batch Update
+
+===== Operation
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/resource-update/batch-update-op
+
+The BATCH UPDATE operation SHALL be implemented as an HTTP PATCH request on the resource collection that contains the resources to be updated.
+====
+
+===== Request Body
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/resource-update/batch-update-request
+
+part:: The URL of the PATCH request SHALL identify the representation to be patched.
+
+part:: The body of the PATCH request SHALL contain a list of change instructions for each resource to be updated in the collection.
+
+part:: Each item in the list SHALL contain the `id` of an existing resource to be updated.
+
+part:: The `Content-Type` header SHALL be set to a media type that defines a proper patch format (e.g. JSON Patch, JSON Merge-Patch).
+====
+
+===== Response
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/resource-update/batch-update-response
+
+conditions:: The request is successful or partially successful
+
+part:: The response body SHALL be valid according to the JSON schema {batch-response-schema}.
+
+part:: For each resource patch included in the request, the response SHALL contain exactly one JSON object with the following data:
+  - The `id` attribute SHALL contain the value of the `id` of the resource as provided in the request.
+  - The `status` attribute SHALL contain the HTTP status code that would have been returned if the resource had been added individually using a REPLACE operation.
+  - The `error` attribute MAY contain an error message describing why the operation failed for this resource.
+====
+
+
+
+==== Optimistic Locking
+
+Only the "Optimistic locking using timestamps" method defined in {ogcapi-features-4} can be used when replacing resources using batch mode.
+
+In this case, the value of the `If-Unmodified-Since` header is compared to the last-modified timestamp of each modified resource.
+
+
+
+[[clause-geojson-batch]]
+==== Batch Mode
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/geojson/batch-format
+
+conditions:: The server implements <<clause-resource-crd,/req/create-replace-delete>>.
+
+A BATCH CREATE or BATCH REPLACE request body SHALL be a valid GeoJSON `FeatureCollection` document.
+====
+
+
+
+
+[[clause-sensorml-batch]]
+==== Batch Mode
+
+Multiple features can be added using the SensorML JSON format when wrapped into a collection object.
+
+[requirement,model=ogc]
+====
+[%metadata]
+identifier:: /req/sensorml/batch-format
+
+conditions:: The server implements <<clause-resource-crd,/req/create-replace-delete>>.
+
+part:: A BATCH CREATE or BATCH REPLACE request SHALL have a `Content-Type` header with value `{sensorml-json-mediatype}`
+
+part:: A BATCH CREATE or BATCH REPLACE request body SHALL be valid against one of the following schemas:
+
+- {sensorml-system-collection-schema}
+- {sensorml-procedure-collection-schema}
+- {sensorml-deployment-collection-schema}
+- {sensorml-property-collection-schema}
+====
+
+
+

api/connectedsystems/api/part1/openapi/README.md

@@ -0,0 +1,5 @@
+# OpenAPI template
+
+## Building
+
+To produce the HTML of the open-api run `redoc-cli bundle -o openapi-movingfeatures-1.html openapi-movingfeatures-1.yaml`.

api/connectedsystems/api/part1/openapi/examples/collections/collectionItem_deployment.json

@@ -0,0 +1,38 @@
+{
+  "type": "Feature",
+  "id": "iv3f2kcq27gfi",
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [[
+      [53.76,-173.7],
+      [53.76,-155.07],
+      [75.03,-155.07],
+      [75.03,-173.7],
+      [53.76,-173.7]
+    ]]
+  },
+  "properties": {
+    "uid": "urn:x-ogc:deployments:D001",
+    "name": "Saildrone - 2017 Arctic Mission",
+    "featureType": "http://www.w3.org/ns/ssn/Deployment",
+    "description": "In July 2017, three saildrones were launched from Dutch Harbor, Alaska, in partnership with NOAA Research...",
+    "validTime": ["2017-07-17T00:00:00Z", "2017-09-29T00:00:00Z"],
+    "members": {
+      "href" : "https://data.example.org/api/deployments/iv3f2kcq27gfi/systems?f=json",
+      "type" : "application/geo+json",
+      "title" : "Deployed Systems"
+    }
+  },
+  "links": [
+    {
+      "rel": "self",
+      "href": "https://data.example.com/api/collections/all_deployments/items/iv3f2kcq27gfi?f=json",
+      "type" : "application/geo+json"
+    },
+    {
+      "rel": "canonical",
+      "href": "https://data.example.com/api/deployments/iv3f2kcq27gfi?f=json",
+      "type" : "application/geo+json"
+    }
+  ]
+}

api/connectedsystems/api/part1/openapi/examples/collections/collectionItem_system.json

@@ -0,0 +1,23 @@
+{
+  "type": "Feature",
+  "id": "SYS001",
+  "geometry": null,
+  "properties": {
+    "featureType": "http://www.w3.org/ns/sosa/Platform",
+    "uid": "urn:x-ogc:systems:uav:solo154",
+    "name": "UAV System 412",
+    "description": "3DR Solo UAV"
+  },
+  "links": [
+    {
+      "rel": "self",
+      "href": "https://data.example.com/api/collections/all_systems/items/SYS001?f=json",
+      "type" : "application/geo+json"
+    },
+    {
+      "rel": "canonical",
+      "href": "https://data.example.com/api/systems/SYS001?f=json",
+      "type" : "application/geo+json"
+    }
+  ]
+}

api/connectedsystems/api/part1/openapi/examples/collections/collectionItems_systems.json

@@ -0,0 +1,22 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "id": "SYS001",
+      "geometry": null,
+      "properties": {
+      }
+    }
+  ],
+  "links": [
+    {
+      "href": "https://data.example.com/api/collections/all_systems/items",
+      "rel": "self"
+    },
+    {
+      "href": "https://data.example.com/api/systems",
+      "rel": "canonical"
+    }
+  ]
+}