AWS neptune documentation change
Summary
Capitalized 'openCypher' to 'OpenCypher' throughout document and added new section about HTTP trailing headers for error handling in multi-part responses
Security assessment
Changes primarily focus on branding consistency and error diagnostics improvements. The trailing headers feature helps detect streaming failures but does not address a specific security vulnerability or introduce security controls. Error visibility improvements are operational rather than security-related.
Diff
diff --git a/neptune/latest/userguide/access-graph-opencypher-queries.md b/neptune/latest/userguide/access-graph-opencypher-queries.md index 0ac30cf33..6786c4a2d 100644 --- a//neptune/latest/userguide/access-graph-opencypher-queries.md +++ b//neptune/latest/userguide/access-graph-opencypher-queries.md @@ -5 +5 @@ -Read and write queriesopenCypher results format +Read and write queriesOpenCypher results formatOptional HTTP trailing headers @@ -7 +7 @@ Read and write queriesopenCypher results format -# The Amazon Neptune openCypher HTTPS endpoint +# The Amazon Neptune OpenCypher HTTPS endpoint @@ -11 +11 @@ Read and write queriesopenCypher results format - * openCypher read and write queries on the HTTPS endpoint + * OpenCypher read and write queries on the HTTPS endpoint @@ -13 +13 @@ Read and write queriesopenCypher results format - * The default openCypher JSON results format + * The default OpenCypher JSON results format @@ -14,0 +15 @@ Read and write queriesopenCypher results format + * Optional HTTP trailing headers for multi-part OpenCypher responses @@ -18 +18,0 @@ Read and write queriesopenCypher results format -## openCypher read and write queries on the HTTPS endpoint @@ -20 +20 @@ Read and write queriesopenCypher results format -The openCypher HTTPS endpoint supports read and update queries using both the `GET` and the `POST` method. The `DELETE` and `PUT` methods are not supported. +## OpenCypher read and write queries on the HTTPS endpoint @@ -22 +22,3 @@ The openCypher HTTPS endpoint supports read and update queries using both the `G -The following instructions walk you through connecting to the openCypher endpoint using the `curl` command and HTTPS. You must follow these instructions from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB instance. +The OpenCypher HTTPS endpoint supports read and update queries using both the `GET` and the `POST` method. The `DELETE` and `PUT` methods are not supported. + +The following instructions walk you through connecting to the OpenCypher endpoint using the `curl` command and HTTPS. You must follow these instructions from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB instance. @@ -57 +59 @@ Here are sample write/update queries, one that uses `POST` and one that uses `GE -## The default openCypher JSON results format +## The default OpenCypher JSON results format @@ -188,0 +191,58 @@ The JSON document that is returned contains one field, `results`, which contains +## Optional HTTP trailing headers for multi-part OpenCypher responses + +This feature is available starting with Neptune engine release [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml). + +The HTTP response to OpenCypher queries and updates is typically returned in multiple chunks. When failures occur after the initial response chunks have been sent (with an HTTP status code of 200), it can be challenging to diagnose the issue. By default, `Neptune reports such failures by appending an error message to the message body, which may be corrupted due to the streaming nature of the response. + +###### Using trailing headers + +To improve error detection and diagnosis, you can enable trailing headers by including a transfer-encoding (TE) trailers header (te: trailers)in your request. Doing this will cause Neptune to include two new header fields within the trailing headers of the response chunks: + + * `X-Neptune-Status` – contains the response code followed by a short name. For instance, in case of success the trailing header would be: `X-Neptune-Status: 200 OK`. In the case of failure, the response code would be a Neptune engine error code such as `X-Neptune-Status: 500 TimeLimitExceededException`. + + * `X-Neptune-Detail` – is empty for successful requests. In the case of errors, it contains the JSON error message. Because only ASCII characters are allowed in HTTP header values, the JSON string is URL encoded. The error message is also still appended to the response message body. + + + + +For more information, see the [MDN page about TE request headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE). + +###### OpenCypher trailing headers usage example + +This example demonstrates how trailing headers help diagnose a query that exceeds its time limit: + + + curl --raw 'https://your-neptune-endpoint:port/openCypher' \ + -H 'TE: trailers' \ + -d 'query=MATCH(n) RETURN n.firstName' + + + Output: + < HTTP/1.1 200 OK + < transfer-encoding: chunked + < trailer: X-Neptune-Status, X-Neptune-Detail + < content-type: application/json;charset=UTF-8 + < + < + { + "results": [{ + "n.firstName": "Hossein" + }, { + "n.firstName": "Jan" + }, { + "n.firstName": "Miguel" + }, { + "n.firstName": "Eric" + }, + {"detailedMessage":"Operation terminated (deadline exceeded)", + "code":"TimeLimitExceededException", + "requestId":"a7e9d2aa-fbb7-486e-8447-2ef2a8544080", + "message":"Operation terminated (deadline exceeded)"} + 0 + X-Neptune-Status: 500 TimeLimitExceededException + X-Neptune-Detail: %7B%22detailedMessage%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%2C%22code%22%3A%22TimeLimitExceededException%22%2C%22requestId%22%3A%22a7e9d2aa-fbb7-486e-8447-2ef2a8544080%22%2C%22message%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%7D + +###### Response breakdown: + +The previous example shows how an OpenCypher response with trailing headers can help diagnose query failures. Here we see four sequential parts: (1) initial headers with a 200 OK status indicating streaming begins, (2) partial (broken) JSON results successfully streamed before the failure, (3) the appended error message showing the timeout, and (4) trailing headers containing the final status (500 TimeLimitExceededException) and detailed error information. +