Migrating from API v1

API v2 Preview

API v2 is coming in an upcoming release. This guide previews the changes to help you prepare for migration. The current release uses API v1.

Quine API v2 will introduce improvements to response formats, error handling, and endpoint organization. This guide previews the key changes to help you prepare for migration.

Why V2?

The v1 API evolved organically as Quine grew, resulting in inconsistencies that made the API harder to learn and use. V2 addresses these issues with a ground-up redesign focused on:

• Predictable patterns — Consistent naming conventions and HTTP method usage across all endpoints
• Better error handling — Structured error responses with typed errors and actionable messages
• Safer responses — Response envelopes that include warnings without breaking existing integrations

API Version Overview

Version	Status	Base Path	Notes
v1	Current	/api/v1/	Current API for all installations
v2	Preview	/api/v2/	Coming in an upcoming release

When v2 releases, both API versions will be available. Plan to migrate to v2 for new development.

Design Principles

V2 follows REST conventions more strictly than v1:

Plural resource names — Collection endpoints use plural nouns (/ingests not /ingest) to distinguish collections from individual resources.

Resource names in request body — When creating resources, the name is part of the resource representation in the request body, not the URL. This allows the server to validate the complete resource definition before accepting it.

POST for actions, PUT for idempotent updates — Actions like pause/start use POST because they trigger state changes. PUT is reserved for idempotent operations where repeating the request produces the same result.

Consistent path structure — Related operations are grouped under the same path prefix (/standing-queries/{name}/outputs instead of /query/standing/{name}/output).

Endpoint Path Changes

The tables below show the mapping from v1 to v2 endpoints. Most changes follow the design principles above.

Admin Endpoints

Admin endpoints manage system configuration, monitoring, and cluster operations. Most admin endpoints remain unchanged since they already followed consistent patterns. The main changes involve clearer naming (build-info → system-info, meta-data → metadata) and restructuring node-specific operations under a /nodes/ path prefix.

v1 Endpoint	v2 Endpoint	Notes
GET /admin/build-info	GET /admin/system-info	Renamed
GET /admin/config	GET /admin/config	Unchanged
GET /admin/graph-hash-code	GET /admin/graph-hash-code	Unchanged
GET /admin/liveness	GET /admin/liveness	Unchanged
GET /admin/meta-data	GET /admin/metadata	Renamed (hyphen removed)
GET /admin/metrics	GET /admin/metrics	Unchanged
GET /admin/readiness	GET /admin/readiness	Unchanged
POST /admin/request-node-sleep/{id}	POST /admin/nodes/{nodeIdSegment}/request-sleep	Restructured path
POST /admin/shard-sizes	GET /admin/shards/size-limits	Split into separate read endpoint
POST /admin/shard-sizes	POST /admin/shards/size-limits	Split into separate write endpoint
POST /admin/shutdown	POST /admin/shutdown	Unchanged

Ingest Endpoints

Ingest endpoints manage data streaming into Quine. The key changes apply the plural naming convention (/ingest → /ingests) and move the stream name from the URL path into the request body when creating new streams. The pause and start operations changed from PUT to POST since they trigger state changes rather than updating resource properties.

v1 Endpoint	v2 Endpoint	Notes
GET /ingest	GET /ingests	Pluralized
POST /ingest/{name}	POST /ingests	Name moved to request body
GET /ingest/{name}	GET /ingests/{name}	Pluralized
DELETE /ingest/{name}	DELETE /ingests/{name}	Pluralized
PUT /ingest/{name}/pause	POST /ingests/{name}/pause	Changed to POST
PUT /ingest/{name}/start	POST /ingests/{name}/start	Changed to 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. V2 reorganizes these endpoints from the generic /query/standing path to /standing-queries, making the API self-documenting. Output management moves the output name from the URL into the request body for consistency with other resource creation patterns.

v1 Endpoint	v2 Endpoint	Notes
GET /query/standing	GET /standing-queries	Restructured path
POST /query/standing/{name}	POST /standing-queries	Name moved to request body
GET /query/standing/{name}	GET /standing-queries/{name}	Restructured path
DELETE /query/standing/{name}	DELETE /standing-queries/{name}	Restructured path
POST /query/standing/{name}/output/{output}	POST /standing-queries/{name}/outputs	Output name in body
DELETE /query/standing/{name}/output/{output}	DELETE /standing-queries/{name}/outputs/{output}	Restructured path
POST /query/standing/control/propagate	PUT /standing-queries/control/propagate	Changed to PUT

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

Cypher Query Endpoints

Cypher query endpoints execute ad-hoc queries against the graph. V2 moves these from /query/cypher to /cypher-queries and uses more descriptive operation names (query-graph, query-nodes, query-edges) that clarify what each endpoint returns.

v1 Endpoint	v2 Endpoint	Notes
POST /query/cypher	POST /cypher-queries/query-graph	Restructured path
POST /query/cypher/nodes	POST /cypher-queries/query-nodes	Restructured path
POST /query/cypher/edges	POST /cypher-queries/query-edges	Restructured path
POST /query/cypher/user-defined	POST /cypher-queries/user-defined	Restructured path

Algorithm Endpoints

Algorithm endpoints perform graph traversal operations like random walks. V2 changes these from GET/PUT to POST since they execute operations rather than retrieving or updating resources. The path structure now groups operations under /algorithm/nodes/{id} to clarify they operate on specific nodes.

v1 Endpoint	v2 Endpoint	Notes
GET /algorithm/walk/{id}	POST /algorithm/nodes/{id}/walk	Changed to POST, restructured
PUT /algorithm/walk	POST /algorithm/save-walk	Changed to POST

Gremlin Endpoints

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

• POST /query/gremlin (deprecated)
• POST /query/gremlin/nodes (deprecated)
• POST /query/gremlin/edges (deprecated)

Use Cypher query endpoints instead.

Query UI Endpoints

Query UI endpoints configure the Exploration UI with sample queries, quick queries, and node appearance customizations. These endpoints remain unchanged in v2 since they already followed consistent patterns.

v1 Endpoint	v2 Endpoint	Notes
GET /query-ui/sample-queries	GET /query-ui/sample-queries	Unchanged
PUT /query-ui/sample-queries	PUT /query-ui/sample-queries	Unchanged
GET /query-ui/quick-queries	GET /query-ui/quick-queries	Unchanged
PUT /query-ui/quick-queries	PUT /query-ui/quick-queries	Unchanged
GET /query-ui/node-appearances	GET /query-ui/node-appearances	Unchanged
PUT /query-ui/node-appearances	PUT /query-ui/node-appearances	Unchanged

Key Changes

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

Response Format

v1 returned raw data directly at the top level of the response body. v2 wraps all responses in structured envelopes with content, message, and warnings fields. Update your response parsing to extract the content field:

# v1
ingest_config = response.json()

# v2
ingest_config = response.json()["content"]

See Response Format for the complete envelope specification.

Error Responses

v1 used varied error formats depending on the error type. v2 returns errors as an array of typed error objects with consistent structure, making error handling more predictable:

{
  "errors": [
    {
      "type": "ApiError",
      "message": "Ingest stream 'my-ingest' does not exist"
    }
  ]
}

Each error object includes a type field (ApiError, DecodeError, CypherError) that indicates how to interpret the remaining fields. This allows clients to handle different error categories appropriately.

See Error Responses for the complete error format specification.

Query Parameters

v2 standardizes common query parameters (namespace, at-time, timeout) that work consistently across all endpoints that support them. 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:

v1:

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

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

v2:

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

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

This applies to ingests and standing queries.

Migration Checklist

1. Update endpoint paths - Use the mapping tables above
2. Update HTTP methods - Some endpoints changed from PUT to POST
3. Move resource names to body - For create operations (ingests, standing queries)
4. Update response parsing - Extract data from content field
5. Handle warnings - Check the warnings array in responses
6. Update error handling - Parse the new structured error format

Questions

Contact support@thatdot.com if you have questions about migration or need assistance.

Related Documentation

• REST API Reference - Interactive API documentation