Migrating from API v1¶

API v1 deprecation

API v1 is planned for deprecation and will be removed in a future release. New integrations should use v2; existing v1 integrations should plan to migrate.

Quine API v2 introduces improvements to response formats, error handling, and endpoint organization. This guide explains the key changes and how to migrate your integrations from v1 to v2.

Why V2?¶

The v1 API evolved organically as Quine grew, resulting in inconsistencies that made the API harder to learn and use. V2 is a ground-up redesign that pins every decision to Google's API Improvement Proposals (AIPs) — the same external design rules Google uses for its own public APIs. Anchoring v2 to a published standard means the rationale for every URL shape, status code, and wire format lives in one citable place rather than tribal knowledge, and well-known client patterns (pagination cursors, RFC 3339 timestamps, structured errors) work without per-endpoint surprises.

Quine is a JSON HTTP API, not a Protobuf/gRPC service, so a few AIP details are assumed by their gRPC tooling rather than written into the proposal text. Where an AIP relies on Protobuf semantics that don't apply to a JSON API (for example, the proto3 default-value-omission rule, or carrying google.protobuf.Any payloads inside an error response), v2 keeps the shape and intent of the AIP but adapts the encoding for plain JSON. Those deviations are called out next to the relevant principle below.

At a glance, v2 is focused on:

Predictable patterns — Consistent naming conventions and HTTP method usage across all endpoints
Graph-scoped operations — Ingest, query, and standing query endpoints are scoped under a named graph (graph/quine), making multi-graph support explicit in the URL
RPC-style actions — Action endpoints use colon-separated verbs (:pause, :resume, :shutdown) to clearly distinguish actions from resource operations
Better error handling — Structured error responses with actionable messages

API Version Overview¶

Version	Status	Base Path	Notes
v2	Current (default)	`/api/v2/`	Default API for all installations
v1	Planned for deprecation	`/api/v1/`	Still mounted by default; will be removed in a future release

Both API versions are currently available. V1 routes remain reachable for backwards compatibility. Migrate to v2 for all new development and plan migration of existing integrations.

Design Principles¶

V2 follows REST conventions more strictly than v1. Each principle below cites the AIP that codifies it; the AIP itself is the authoritative source for edge cases and rationale.

Graph-scoped resources (AIP-121 resource-oriented design, AIP-122 resource names) — Operations on ingests, standing queries, Cypher, and algorithms are scoped under /graph/quine/ in the URL path. Quine uses a single graph named quine. Scoping at the URL level (rather than via a query parameter) makes the parent–child relationship part of the resource name, so a single ingest or standing query has one canonical URL even across graphs.

RPC-style action verbs (AIP-136 custom methods) — Action endpoints use a colon-separated verb suffix (e.g., ingests/{ingestName}:pause, system:shutdown). The colon syntax keeps actions on the same path as the resource they act on without misrepresenting them as sub-resources, so URL trees stay shaped around nouns while still naming verbs explicitly.

camelCase path segments (AIP-122 resource names) — Path segments use camelCase (standingQueries, shardSizeLimits, systemInfo) instead of kebab-case (standing-queries, shard-sizes, system-info). This matches the camelCase JSON field convention from AIP-140, so an identifier looks the same whether it appears in a URL or a request body.

System endpoints at top level — Administrative endpoints are grouped under /system/ (renamed from /admin/). Treating "system" as a top-level category (rather than a peer of every per-graph collection) keeps /graph/quine/… reserved for graph-scoped resources.

Plural resource names (AIP-122 resource names) — Collection endpoints use plural nouns (/ingests not /ingest) so the URL itself signals "this addresses many" vs. /ingests/{ingestName} for "this addresses one."

Resource names in request body (AIP-133 standard Create) — When creating resources, the name is part of the resource representation in the request body, not the URL. The server validates the complete resource definition (name + configuration) atomically before accepting it, and the same JSON document round-trips through GET/PUT/POST without callers having to splice the name in and out of the URL.

POST for actions, PUT for idempotent updates (AIP-133 / AIP-134 / AIP-136) — Actions like :pause/:resume use POST because they trigger state changes and are not required to be idempotent. PUT is reserved for idempotent operations where repeating the request produces the same result; DELETE removes a resource and is also idempotent.

Endpoint Path Changes¶

The tables below show the mapping from v1 to v2 endpoints. All v2 paths are relative to /api/v2/.

System Endpoints¶

System endpoints (formerly "admin") manage system configuration, monitoring, and cluster operations. These have moved from /admin/ to /system/ and path segments now use camelCase.

v1 Endpoint	v2 Endpoint	Notes
`GET /admin/build-info`	`GET /system/systemInfo`	Renamed, moved to `/system/`
`GET /admin/config`	`GET /system/config`	Moved to `/system/`
`GET /admin/graph-hash-code`	`GET /graph/quine/hashCode`	Graph-scoped, camelCase
`GET /admin/liveness`	`GET /system/liveness`	Moved to `/system/`
`GET /admin/metrics`	`GET /system/metrics`	Moved to `/system/`
`GET /admin/readiness`	`GET /system/readiness`	Moved to `/system/`
`POST /admin/request-node-sleep/{id}`	—	Removed
`POST /admin/shard-sizes`	`GET /system/shardSizeLimits`	Split into GET, moved, camelCase
`POST /admin/shard-sizes`	`PATCH /system/shardSizeLimits`	Split into PATCH, moved, camelCase
`POST /admin/shutdown`	`POST /system:shutdown`	RPC-style verb

Ingest Endpoints¶

Ingest endpoints manage data streaming into Quine. In v2, ingest operations are scoped under a named graph (/graph/quine/ingests). The stream name moved from the URL path to the request body when creating streams, and pause/resume operations use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`GET /ingest`	`GET /graph/quine/ingests`	Graph-scoped, pluralized
`POST /ingest/{name}`	`POST /graph/quine/ingests`	Name moved to request body
`GET /ingest/{name}`	`GET /graph/quine/ingests/{ingestName}`	Graph-scoped, param renamed
`DELETE /ingest/{name}`	`DELETE /graph/quine/ingests/{ingestName}`	Graph-scoped, param renamed
`PUT /ingest/{name}/pause`	`POST /graph/quine/ingests/{ingestName}:pause`	RPC-style verb, POST
`PUT /ingest/{name}/start`	`POST /graph/quine/ingests/{ingestName}:resume`	Renamed to `:resume`, POST

For ingest stream configuration and usage, see Ingest Streams.

Standing Query Endpoints¶

Standing queries are continuously-running pattern matchers that execute actions when patterns are detected in the graph. In v2, standing query operations are scoped under a named graph. Path segments use camelCase, and output management moves the output name into the request body.

v1 Endpoint	v2 Endpoint	Notes
`GET /query/standing`	`GET /graph/quine/standingQueries`	Graph-scoped, camelCase
`POST /query/standing/{name}`	`POST /graph/quine/standingQueries`	Name moved to request body
`GET /query/standing/{name}`	`GET /graph/quine/standingQueries/{standingQueryName}`	Graph-scoped, camelCase
`DELETE /query/standing/{name}`	`DELETE /graph/quine/standingQueries/{standingQueryName}`	Graph-scoped, camelCase
`POST /query/standing/{name}/output/{output}`	`POST /graph/quine/standingQueries/{standingQueryName}/outputs`	Output name in body
`DELETE /query/standing/{name}/output/{output}`	`DELETE /graph/quine/standingQueries/{standingQueryName}/outputs/{standingQueryOutputName}`	Graph-scoped, camelCase
`POST /query/standing/control/propagate`	`POST /graph/quine/standingQueries:propagate`	RPC-style verb

For standing query configuration and output destinations, see Standing Queries.

Cypher Query Endpoints¶

Cypher query endpoints execute ad-hoc queries against the graph. In v2, these are scoped under a named graph and use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`POST /query/cypher`	`POST /graph/quine/cypher:query`	Graph-scoped, RPC verb
`POST /query/cypher/nodes`	`POST /graph/quine/cypher:queryNodes`	Graph-scoped, RPC verb
`POST /query/cypher/edges`	`POST /graph/quine/cypher:queryEdges`	Graph-scoped, RPC verb

Algorithm Endpoints¶

Algorithm endpoints perform graph traversal operations like random walks. In v2, these are scoped under a named graph and use RPC-style verbs.

v1 Endpoint	v2 Endpoint	Notes
`GET /algorithm/walk/{id}`	`POST /graph/quine/algorithms/randomWalk/nodes/{nodeId}:generateRandomWalk`	Graph-scoped, RPC verb, param renamed
`PUT /algorithm/walk`	`POST /graph/quine/algorithms/randomWalk:saveWalks`	Graph-scoped, RPC verb

Query UI Endpoints¶

Query UI endpoints configure the Exploration UI with sample queries, quick queries, and node appearance customizations. These have moved to camelCase path segments.

v1 Endpoint	v2 Endpoint	Notes
`GET /query-ui/sample-queries`	`GET /queryUi/sampleQueries`	camelCase
`PUT /query-ui/sample-queries`	`PUT /queryUi/sampleQueries`	camelCase
`GET /query-ui/quick-queries`	`GET /queryUi/quickQueries`	camelCase
`PUT /query-ui/quick-queries`	`PUT /queryUi/quickQueries`	camelCase
`GET /query-ui/node-appearances`	`GET /queryUi/nodeAppearances`	camelCase
`PUT /query-ui/node-appearances`	`PUT /queryUi/nodeAppearances`	camelCase

Gremlin Endpoints¶

Gremlin was an alternative graph query language supported in v1. These endpoints are not available in v2. Cypher provides equivalent functionality with better performance and a more intuitive syntax:

POST /query/gremlin (v1 only)
POST /query/gremlin/nodes (v1 only)
POST /query/gremlin/edges (v1 only)

Use Cypher query endpoints instead.

Key Changes¶

This section describes behavioral changes that affect how you interact with the API, regardless of which endpoints you use.

Response Format¶

Both v1 and v2 return data directly at the top level of the response body. List endpoints in v2 return a paginated envelope with items and nextPageToken fields per AIP-158 (pagination). v2 201 responses may include a Warning header with advisory messages.

The envelope wraps every list response over a user-managed collection (ingests, standing queries, namespaces, …) even when server-side paging is not currently implemented for that endpoint — the wrapper itself is the forward-compatibility contract. Changing from a bare array to an envelope later would be breaking, so v2 ships the envelope up front and nextPageToken is simply omitted when there are no further pages.

A small number of admin-curated configuration endpoints (/queryUi/sampleQueries, /queryUi/quickQueries, /queryUi/nodeAppearances) deliberately return bare arrays rather than a Page envelope. They are closed configuration blobs rather than user-managed collections, so paging serves no purpose and the bare-array shape is documented at the endpoints themselves.

See Response Format for the complete response specification.

Error Responses¶

v1 used varied error formats depending on the error type. v2 returns a unified ApiError envelope shaped after AIP-193 / google.rpc.Status:

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "Ingest stream 'my-ingest' does not exist",
    "details": []
  }
}

The error object includes code (the HTTP status code), status (the canonical AIP-193 status string such as INVALID_ARGUMENT or NOT_FOUND), message (the primary human-readable error), and details (additional structured context — request IDs, hints, machine-readable error classifications). Pinning the wire format to AIP-193 means clients can parse errors with one branch of code and get a stable status field for switching, instead of grepping message strings.

Because Quine is a JSON API rather than a Protobuf service, the details[] entries are modelled as a closed, type-discriminated union (RequestInfo, Help, ErrorInfo) instead of AIP-193's open google.protobuf.Any carrier. The shape mirrors google.rpc.ErrorInfo and friends for familiarity, but new variants are added by extending the union rather than packing arbitrary proto messages.

See Error Responses for the complete error format specification.

Enum Wire Format¶

Sealed-trait enumerations encode to SCREAMING_SNAKE_CASE strings per AIP-126 (e.g. RUNNING, INVALID_ARGUMENT). The PascalCase identifiers stay in idiomatic Scala source; conversion happens at the codec boundary. Where the wire value must mirror an external system (e.g. Kafka's PLAINTEXT/latest), the codec uses an explicit literal instead of the AIP-126 default — those cases are documented at the field.

Type discriminators on sum types — the "type": "<Kind>" field on ingest, output, and credential configurations — are a deliberate exception: discriminator values use bare PascalCase names ("type": "Kinesis", not "type": "KINESIS" or "type": "KinesisIngest"). AIP-126 covers enum values, not ADT type tags, and PascalCase discriminator values read more naturally next to the Scala class names they identify.

Query Parameters¶

v2 standardizes common query parameters using camelCase names (atTime, timeout) that work consistently across all graph-scoped endpoints that support them. Per AIP-142 (time and duration), timestamps use RFC 3339 format (e.g., 2026-04-27T15:30:00Z) instead of epoch milliseconds, and durations use Go-style strings (e.g., 20s, 500ms, 1.5m) instead of millisecond integers. Both formats are self-describing and round-trip through standard JSON tooling. The namespace query parameter from previous versions is replaced by the graph name in the URL path (/graph/{graphName}/...). See Query Parameters for usage details.

Resource Creation Pattern¶

API v2 uses a consistent pattern for creating resources where the resource name is in the request body rather than the URL path, and the resource is scoped to a graph:

v1:

POST /api/v1/ingest/my-ingest-name
Content-Type: application/json

{ "type": "FileIngest", ... }

v2:

POST /api/v2/graph/quine/ingests
Content-Type: application/json

{ "name": "my-ingest-name", "type": "FileIngest", ... }

This applies to ingests and standing queries.

Migration Checklist¶

Update base paths — /admin/ is now /system/; data operations are now under /graph/quine/
Update to camelCase — Path segments changed from kebab-case to camelCase (e.g., standing-queries → standingQueries)
Adopt RPC-style verbs — Action endpoints use colon verbs (e.g., /ingests/{name}/pause → /ingests/{ingestName}:pause)
Update HTTP methods — Some endpoints changed from PUT/GET to POST
Move resource names to body — For create operations (ingests, standing queries)
Update parameter names — name → ingestName, id → nodeId, standing-query-name → standingQueryName
Update query parameter formats — at-time → atTime (RFC 3339 timestamp), timeout → timeout (duration string like 20s)
Update error handling — Parse the new structured ApiError format with code, status, message, details

REST API Reference - Interactive API documentation