GraphQL API Overview

The Aster Policy Engine exposes a GraphQL API for querying and managing policies. It is built on SmallRye GraphQL (the MicroProfile GraphQL implementation) and offers the full suite of MicroProfile GraphQL features including built-in introspection, type safety, and a hosted schema endpoint.

Endpoint

Purpose	URL
Query / Mutation execution	POST /graphql
Schema (SDL)	GET /graphql/schema.graphql

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes
X-Tenant-Id	Tenant identifier string	Yes
Idempotency-Key	Client-generated unique string (UUID recommended)	Mutations only

Idempotency-Key

Providing an Idempotency-Key on mutation requests ensures that retrying a failed or timed-out request does not apply the operation a second time. The server caches the mutation result keyed on this value for 24 hours. This header is optional but strongly recommended for write operations.

Request Format

All requests must be HTTP POST with a JSON body conforming to the GraphQL over HTTP specification:

{
  "query": "query { ... }",
  "variables": {},
  "operationName": "OptionalOperationName"
}

Field	Type	Required	Description
query	string	Yes	GraphQL document containing the operation to execute.
variables	object	No	Named variable values referenced in the query.
operationName	string	No	Disambiguates which operation to run when query contains multiple named operations.

Response Format

{
  "data": {},
  "errors": []
}

A 200 OK HTTP status is returned for all well-formed GraphQL responses, including partial successes. Always inspect the errors array — a non-empty value indicates that one or more field resolvers encountered an error, even when data is partially populated.

Schema

Download the full schema in SDL format:

curl

curl -X GET https://policy.aster-lang.dev/graphql/schema.graphql \
  -H "Authorization: Bearer <token>"

Error Handling

GraphQL errors follow the GraphQL specification error format:

{
  "data": null,
  "errors": [
    {
      "message": "Policy not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["getPolicy"],
      "extensions": {
        "code": "NOT_FOUND",
        "classification": "DataFetchingException"
      }
    }
  ]
}

Extension Field	Description
code	Machine-readable error code (e.g. NOT_FOUND, FORBIDDEN, VALIDATION_ERROR).
classification	SmallRye GraphQL error classification.

HTTP Status Codes

Status	Meaning
200 OK	GraphQL response returned (check errors for partial failures).
400 Bad Request	Request body is not valid JSON or the GraphQL document is syntactically invalid.
401 Unauthorized	Missing or invalid bearer token.
403 Forbidden	Token is valid but the caller lacks the required role for the requested operation.
500 Internal Server Error	Unexpected engine failure before the GraphQL layer could respond.