Add rate limiting

Author: nickevansuk

EditorsDraft/edit.html

@@ -1160,7 +1160,7 @@
 <pre class="example" title="Order Creation: OrderQuote example success response" data-transform="dataExampleOrderQuoteCreationResponse">
 </pre>
 
-If there are any issues with the `orderedItem`s provided in the `OrderQuote`, the <a>Booking System</a> MUST respond with a `409 Conflict` response, with `error` details provided against each offending `OrderItem`. Note that `totalPaymentDue` and `totalTaxSpecification` MUST be calculated excluding any `OrderItem`s that include `error`s.
+If there are any issues with the `orderedItem`s provided in the `OrderQuote`, the <a>Booking System</a> MUST respond with a `409 Conflict` response (as the error is expected to be resolved, and the request resubmitted, as per [[RFC2616]]), with `error` details provided against each offending `OrderItem`. Note that `totalPaymentDue` and `totalTaxSpecification` MUST be calculated excluding any `OrderItem`s that include `error`s.
 
 <pre class="example" title="Order Creation: OrderQuote example OrderItem error response" data-transform="dataExampleOrderQuoteCreationOrderItemErrorResponse">
 </pre>
@@ -1171,7 +1171,6 @@
 </pre>
 
 
-
 #### `Order`
 
 A PUT request to the Order Creation endpoint of the <a>Booking System</a> with an object of type `Order` will create the `Order` and complete the booking from the point of the view of the <a>Booking System</a>.
@@ -1605,10 +1604,13 @@
 | `IncompleteCustomerDetailsError`            | 400         | If the `email` address of the customer is not supplied within a `schema:Person` object; or if the `customer` property supplied is not a valid `schema:Person` or `schema:Organization` object. |
 | `IncompleteBrokerDetailsError`              | 400         | If there is insufficient detail in the `schema:Organisation` object describing the <a>Broker</a>; or if the `broker` property supplied is not a valid schema:Organisation object. |
 | `IncompletePaymentDetailsError`             | 400         | If the `payment` property of the `Order` is missing or does not include an `identifier` or `paymentMethod`. |
+| `OrderAlreadyExistsError`                   | 400         | If the UUID used for an `OrderQuote` already represents a completed Order. |
 
 
 #### Order Creation - `OrderItem` errors
 
+Note that all `OrderItem` errors for an `OrderQuote` request result in a `409 Conflict` response, as the error is expected to be resolved, and the request resubmitted, as per [[RFC2616]] section 10.4.10.
+
 | Error Type                                  | Status Code | Use Case                                                                                                                                                                                       |
 |---------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `IncompleteOrderItemError`                  | 409         | If there is a missing `acceptedOffer` or `orderedItem` property on the `schema:OrderItem`. |
@@ -1634,6 +1636,7 @@
 
 | Error Type                                  | Status Code | Use Case                                                                                                                                                                                       |
 |---------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `TemporarilyUnableToProduceOrderQuoteError` | 500         | If the <a>Booking System</a> is unable for technical reasons to produce an `OrderQuote` where the data provided to it is sufficient to allow it to do so. |
 | `TemporarilyUnableToCreateOrderError`       | 500         | If the <a>Booking System</a> is unable for technical reasons to create an `Order` where the data provided to it is sufficient to allow it to do so. |
 | `TemporarilyUnableToUpdateOrderError`       | 500         | If the <a>Booking System</a> is unable for technical reasons to update an `Order` (which includes attempting to PATCH for cancellation) where the data provided to it is sufficient to allow it to do so. |
 | `TemporarilyUnableToDeleteOrderError`       | 500         | If the <a>Booking System</a> is unable for technical reasons to delete an `Order` where the data provided to it is sufficient to allow it to do so |
@@ -1648,6 +1651,9 @@
 | `NotFoundError`                             | 404         | Where a <a>Booking System</a> does not have the generic resource specified. |
 | `MethodNotAllowed`                          | 405         | Where a <a>Booking System</a> does not recognise a specific HTTP method for the endpoint requested with that specific HTTP verb. |
 | `GoneError`                                 | 410         | Where an `Order` has been soft-deleted by an Order Deletion request. |
+| `TooManyRequestsError`                      | 429         | Where the <a>Booking System</a> is rate-limiting the <a>Broker</a>. |
+
+
 
 
 </section>
@@ -1719,19 +1725,23 @@
 
 ## Errors
 
-Error responses MUST be served using an appropriate HTTP 4XX status code or HTTP
-5XX status code specified in the model.
+Error responses MUST be served using an appropriate HTTP 4XX status code or HTTP 5XX status code specified in the model.
 
-All error responses from this API MUST be returned in a JSON-LD format using a
-content type of `application/vnd.openactive+json`, and optionally any version
-parameters, and include at least one `OpenBookingError` object.
+All error responses from this API MUST be returned in a JSON-LD format subclass of the `OpenBookingError` using a content type of `application/vnd.openactive+json` (optionally including any version parameters).
 
-<pre class="example" title="Error response format">
-{
-  "@context": "https://openactive.io/",
-  "type": "IncompleteCustomerDetailsError",
-  "description": "No customer details supplied"
-}
+<pre class="example" title="Error response example" data-transform="dataExampleErrorResponse">
+</pre>
+
+
+## Rate Limiting
+
+The <a>Booking System</a> MAY choose to apply rate limiting for each unique set of authentication credentials, in which case they MUST adhere to the following.
+
+All rate-limited responses from this API MUST return a JSON-LD format `TooManyRequestsError` object using a content type of `application/vnd.openactive+json` (optionally including any version parameters).
+
+The response MUST also include the `Retry-After` HTTP Header with a value set to the number of seconds after which the <a>Broker</a> SHOULD retry as per [[RFC2616]] section 14.37.
+
+<pre class="example" title="Rate limited response example" data-transform="dataExampleRateLimitResponse">
 </pre>
 
 

EditorsDraft/examples.js

@@ -46,13 +46,39 @@ function dataExampleOrderQuoteCreationOrderItemErrorResponse(utils, content) {
 }
 
 function dataExampleOrderQuoteCreationErrorResponse(utils, content) {
+  return generateResponse("500 Internal Server Error", null, OPERATIONS_MEDIA_TYPE, {
+    "@context": CONTEXT,
+    "type": "TemporarilyUnableToProduceOrderQuoteError",
+    "description": "Temporary error occurred in the database"
+  });
+}
+
+function dataExampleErrorResponse(utils, content) {
   return generateResponse("400 Bad Request", null, OPERATIONS_MEDIA_TYPE, {
     "@context": CONTEXT,
     "type": "IncompleteCustomerDetailsError",
     "description": "No customer details supplied"
   });
 }
 
+function dataExampleRateLimitResponse(utils, content) {
+  return generateResponseWithHeaders("429 Too Many Requests", null, OPERATIONS_MEDIA_TYPE,
+    "Retry-After: 8", {
+      "@context": CONTEXT,
+      "type": "TooManyRequestsError",
+      "description": "Rate Limit Reached. Retry in 8 seconds."
+    });
+}
+
+//TODO: Include rate limiting scheme!! [DONE]
+
+
+//TODO: A page on the OA docs site summarising what you can do and can't do with the OpenActive booking specification (to talk through with operators)
+//TODO: Read Iain's slides and stephenage notes from a while back to check we've not missed anything
+
+
+//TODO: Allow for a "lite" signup-only / no cancellation version to exist? No point, it's too simple to need a spec for that...?
+
 //TODO: Allow multiple errors only for order creation
 
 //TODO: Should we have a separate type for OrderRequest to better define the required params?
@@ -645,6 +671,10 @@ function generateRequest(verb, path, mediaType, json) {
   return generateRequestHeaders(verb, path, mediaType) + (json ? "\n\n" + jsonStringify(json) : "");
 }
 
+function generateResponseWithHeaders(responseCode, path, mediaType, headers, json) {
+  return generateResponseHeaders(responseCode, path, mediaType) + "\n" + headers + (json ? "\n\n" + jsonStringify(json) : "");
+}
+
 function generateResponse(responseCode, path, mediaType, json) {
   return generateResponseHeaders(responseCode, path, mediaType) + (json ? "\n\n" + jsonStringify(json) : "");
 }