Metadata API Reference¶

Introduction¶

The metadata API is primarily intended to be used as an admin API to manage the Hasura metadata.

Endpoint¶

All requests are POST requests to the /v1/metadata endpoint.

Request structure¶

POST /v1/metadata HTTP/1.1

{
   "type": <query-type>,
   "version": <Integer> (optional),
   "resource_version": <Integer> (optional),
   "args": <args-object>
}

The structure of args depends on the type and version.

Query

Request types¶

The various types of queries are listed in the following table:

See:

• Tables/Views
• Custom SQL Functions
• Relationships
• Computed Fields
• Permissions
• Inherited Roles
• Remote Schema Permissions
• Event Triggers
• Remote Schemas
• Query Collections
• Custom Types
• Actions
• Manage Metadata

Response structure¶

Request specific

{
    "path"  : String,
    "error" : String
}

{
    "error" : String
}

{
    "error" : String
}

Disabling metadata API¶

Since this API can be used to make changes to the GraphQL schema, it can be disabled, especially in production deployments.

The enabled-apis flag or the HASURA_GRAPHQL_ENABLED_APIS env var can be used to enable/disable this API. By default, the schema/metadata API is enabled. To disable it, you need to explicitly state that this API is not enabled i.e. remove it from the list of enabled APIs.

# enable only graphql api, disable metadata and pgdump
--enabled-apis="graphql"
HASURA_GRAPHQL_ENABLED_APIS="graphql"

See GraphQL Engine server config reference for info on setting the above flag/env var.

Metadata Resource Versioning¶

Metadata is versioned with an optional resource_version field in operations and responses.

This is intended to allow for feedback when replacing metadata with modifications to an out-of-date copy.

The resource_version supplied must match the version returned otherwise a 409 error response is returned.

The version is incremented on any operation that modified metadata as well as reload_metadata.