Neptune Gremlin API

openapi: 3.1.0
info:
  title: Amazon Neptune Neptune Gremlin API
  description: >-
    Apache TinkerPop Gremlin graph traversal language API for querying
    property graphs in Neptune. It supports both WebSocket and HTTP REST
    endpoints for submitting Gremlin traversals. This spec covers the HTTP
    REST endpoint. Neptune supports Gremlin as defined in Apache TinkerPop
    and uses HTTP/1.1 with HTTPS only.
  version: '2024-01-01'
  contact:
    name: Amazon Web Services
    url: https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-gremlin.html
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{cluster-endpoint}:8182
  description: Neptune Gremlin HTTP REST endpoint
  variables:
    cluster-endpoint:
      default: your-cluster-endpoint.region.neptune.amazonaws.com
      description: The cluster endpoint DNS name for your Neptune DB cluster
security:
- aws_sigv4: []
tags:
- name: Query
  description: Submit Gremlin graph traversal queries
- name: Status
  description: Query status and cancellation operations
paths:
  /gremlin:
    post:
      operationId: executeGremlinTraversal
      summary: Amazon Neptune Execute a Gremlin Traversal via HTTP POST
      description: >-
        Submits a Gremlin traversal query to the Neptune HTTP REST endpoint.
        The query is provided as a JSON body with a gremlin property containing
        the traversal string. All results are returned in a single JSON
        response by default. For large result sets, chunked responses can be
        enabled to avoid OutOfMemoryError.
      tags:
      - Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GremlinQueryRequest'
            examples:
              vertexCount:
                summary: Count all vertices
                value:
                  gremlin: g.V().count()
              limitedVertices:
                summary: Get first vertex
                value:
                  gremlin: g.V().limit(1)
              addVertex:
                summary: Add a vertex
                value:
                  gremlin: g.addV('person').property('name','John')
      responses:
        '200':
          description: Gremlin traversal executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GremlinQueryResponse'
              examples:
                executeGremlinTraversal200Example:
                  summary: Default executeGremlinTraversal 200 response
                  x-microcks-default: true
                  value:
                    requestId: neptune-cluster-abc123
                    status:
                      message: example-value
                      code: 1
                      attributes: {}
                    result:
                      data: example-value
                      meta: {}
        '400':
          description: Bad request - malformed Gremlin traversal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GremlinErrorResponse'
              examples:
                executeGremlinTraversal400Example:
                  summary: Default executeGremlinTraversal 400 response
                  x-microcks-default: true
                  value:
                    requestId: neptune-cluster-abc123
                    code: example-value
                    detailedMessage: example-value
        '408':
          description: Query timed out before completing.
        '500':
          description: Internal server error during query execution.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: executeGremlinTraversalGet
      summary: Amazon Neptune Execute a Gremlin Traversal via HTTP GET
      description: >-
        Submits a Gremlin traversal query via a URL query parameter. This
        is an alternative to the POST method for simple queries.
      tags:
      - Query
      parameters:
      - name: gremlin
        in: query
        required: true
        description: The Gremlin traversal query string (URL-encoded).
        schema:
          type: string
        example: g.V().count()
      responses:
        '200':
          description: Gremlin traversal executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GremlinQueryResponse'
              examples:
                executeGremlinTraversalGet200Example:
                  summary: Default executeGremlinTraversalGet 200 response
                  x-microcks-default: true
                  value:
                    requestId: neptune-cluster-abc123
                    status:
                      message: example-value
                      code: 1
                      attributes: {}
                    result:
                      data: example-value
                      meta: {}
        '400':
          description: Bad request - malformed Gremlin traversal.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /gremlin/status:
    get:
      operationId: getGremlinQueryStatus
      summary: Amazon Neptune Get the Status of All Running Gremlin Queries
      description: >-
        Returns the status of all running and waiting Gremlin queries,
        including query IDs, query strings, and execution statistics.
      tags:
      - Status
      responses:
        '200':
          description: Query status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GremlinQueryStatusList'
              examples:
                getGremlinQueryStatus200Example:
                  summary: Default getGremlinQueryStatus 200 response
                  x-microcks-default: true
                  value:
                    acceptedQueryCount: 1
                    runningQueryCount: 1
                    queries:
                    - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /gremlin/status/{queryId}:
    get:
      operationId: getGremlinQueryStatusById
      summary: Amazon Neptune Get the Status of a Specific Gremlin Query
      description: >-
        Returns the status of a specific Gremlin query identified by its
        query ID, including the query string and execution statistics.
      tags:
      - Status
      parameters:
      - name: queryId
        in: path
        required: true
        description: The unique identifier of the Gremlin query.
        schema:
          type: string
      responses:
        '200':
          description: Query status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GremlinQueryStatusDetail'
              examples:
                getGremlinQueryStatusById200Example:
                  summary: Default getGremlinQueryStatusById 200 response
                  x-microcks-default: true
                  value:
                    queryId: neptune-cluster-abc123
                    queryString: example-value
                    queryEvalStats:
                      waited: 1
                      elapsed: 1
                      cancelled: true
                      subqueries: {}
        '404':
          description: Query with the specified ID was not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: cancelGremlinQuery
      summary: Amazon Neptune Cancel a Running Gremlin Query
      description: >-
        Cancels a running Gremlin query by its query ID. The query must
        be currently running or waiting in the queue.
      tags:
      - Status
      parameters:
      - name: queryId
        in: path
        required: true
        description: The unique identifier of the Gremlin query to cancel.
        schema:
          type: string
      responses:
        '200':
          description: Query cancelled successfully.
        '404':
          description: Query with the specified ID was not found.
        '500':
          description: Failed to cancel the query.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    aws_sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication via IAM
  schemas:
    GremlinQueryRequest:
      type: object
      required:
      - gremlin
      properties:
        gremlin:
          type: string
          description: >-
            The Gremlin traversal query string. Must be a valid Gremlin
            traversal starting with g. The bindings property is not
            supported by Neptune.
          examples:
          - g.V().count()
          - g.V().has('name','John').out('knows')
    GremlinQueryResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: The unique request identifier.
        status:
          type: object
          properties:
            message:
              type: string
            code:
              type: integer
              description: The response status code (200 for success).
            attributes:
              type: object
              description: Additional response attributes.
        result:
          type: object
          properties:
            data:
              description: >-
                The query result data. The shape depends on the traversal's
                terminal step (e.g., count, valueMap, path).
            meta:
              type: object
    GremlinErrorResponse:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        code:
          type: string
          description: The error code.
        detailedMessage:
          type: string
          description: A detailed description of the error.
    GremlinQueryStatusList:
      type: object
      properties:
        acceptedQueryCount:
          type: integer
          description: The total number of accepted queries.
        runningQueryCount:
          type: integer
          description: The number of currently running queries.
        queries:
          type: array
          description: The list of running and waiting queries.
          items:
            $ref: '#/components/schemas/GremlinQueryStatusDetail'
    GremlinQueryStatusDetail:
      type: object
      properties:
        queryId:
          type: string
          description: The unique query identifier.
        queryString:
          type: string
          description: The Gremlin traversal query string.
        queryEvalStats:
          type: object
          description: Query execution statistics.
          properties:
            waited:
              type: integer
              description: The time the query waited in the queue (milliseconds).
            elapsed:
              type: integer
              description: The elapsed execution time (milliseconds).
            cancelled:
              type: boolean
              description: Whether the query was cancelled.
            subqueries:
              type: object
              description: Statistics for subqueries, if any.