GraphQL API

Overview

ODP provides a GraphQL endpoint that auto-generates queries and mutations from the database schema. The schema is built dynamically from SchemaOverview — both user-defined collections and system collections (odp_ prefix) are available.

Two endpoints are provided:

• /graphql — Full schema (all collections the user has access to)
• /graphql/system — System collections only (odp_ prefix)

---

Endpoints

POST /graphql

Execute a GraphQL query or mutation against the full schema.

Auth required: Yes (permissions enforced per-collection via accountability)

Request Body:

{
  "query": "query { articles { id title status } }",
  "variables": { "limit": 10 },
  "operationName": "GetArticles"
}

Field	Type	Required	Description
query	string	Yes	GraphQL document
variables	object	No	Variable values for the query
operationName	string	No	Operation to execute (for multi-operation documents)

Response (success):

{
  "data": {
    "articles": [
      { "id": "uuid", "title": "Hello World", "status": "published" }
    ]
  }
}

Response (error):

{
  "errors": [
    { "message": "Cannot query field 'nonexistent' on type 'articles'" }
  ]
}

---

GET /graphql

Execute a GraphQL query via URL query parameter (useful for GraphiQL).

Query Parameters:

• query — GraphQL query string

Response: Same as POST.

---

POST /graphql/system

Execute a GraphQL query against system collections only.

Auth required: Yes

The schema is filtered to only include collections whose names start with odp_. Relations between non-system collections are excluded.

Example:

{
  "query": "query { odp_users { id email status role } }"
}

---

Schema Generation

The GraphQL schema is auto-generated from the SchemaOverview at request time. For each accessible collection, ODP generates:

Query Types

• {collection} — List items (returns array)
• {collection}_by_id — Read single item by primary key

Mutation Types

• create_{collection}_item — Create one item
• update_{collection}_item — Update one item
• delete_{collection}_item — Delete one item
• create_{collection}_items — Bulk create
• update_{collection}_items — Bulk update
• delete_{collection}_items — Bulk delete

Input Types

Each collection gets an input type create_{collection}_input and update_{collection}_input with all writable fields.

---

Permissions

GraphQL queries respect the same RBAC permissions as REST:

• accountability from the request is passed to GraphQLService
• Field-level permissions are enforced — inaccessible fields are excluded from the schema
• Collection-level read/write/delete permissions apply to queries and mutations

---

Example Queries

Query with filtering:

query GetPublishedArticles {
  articles(filter: { status: { _eq: "published" } }, sort: ["-date_created"], limit: 20) {
    id
    title
    date_created
    author {
      first_name
      last_name
    }
  }
}

Mutation:

mutation CreateArticle($data: create_articles_input!) {
  create_articles_item(data: $data) {
    id
    title
  }
}

Variables:

{
  "data": {
    "title": "My New Article",
    "status": "draft"
  }
}

System query:

query GetSystemUsers {
  odp_users(limit: 10) {
    id
    email
    status
    role {
      name
    }
  }
}

---

Implementation Notes

• GraphQLService extends ItemsService — same permission checks apply
• The schema is rebuilt per-request (may be cached if schema caching is enabled)
• Subscriptions are not supported via GraphQL — use WebSocket for real-time updates
• The system schema filter in /graphql/system removes all non-odp_ collections and their relations

---

Configuration

No specific environment variables for GraphQL. General API settings apply:

• ACCESS_TOKEN_TTL — Token validity for authentication
• CACHE_SCHEMA — Whether the schema is cached (improves performance)