rest0.2.0

extend schema
  @link(url: "https://specs.grafbase.com/grafbase", import: ["InputValueSet", "UrlTemplate", "JsonTemplate"])

"""
@restEndpoint directive enables defining named REST endpoints for the schema.
The directive can be used multiple times on a schema to define different endpoints.

Example:
extend schema
  @restEndpoint(name: "weather", baseURL: "https://api.weather.com")
  @restEndpoint(name: "users", baseURL: "https://api.users.example.com")
"""
directive @restEndpoint(
  """
  A unique identifier for the REST endpoint
  """
  name: String!
  """
  The base URL for the REST API
  """
  baseURL: String!
) repeatable on SCHEMA

"""
@rest directive allows you to define RESTful API integrations for GraphQL fields.
This directive maps GraphQL fields to REST endpoints, enabling seamless integration
between your GraphQL schema and external REST APIs.

Example:
type Query {
  users: [User] @rest(
    endpoint: "users",
    method: GET,
    path: "/users",
    selection: "*"
  )
}
"""
directive @rest(
  """
  The name of the REST endpoint to use, as defined by @restEndpoint
  """
  endpoint: String!

  """
  The HTTP method to use for the request, such as GET, POST, etc.
  """
  method: HttpMethod!

  """
  The path template for the request, which can include
  variable substitutions from GraphQL arguments.
  This supports templating using GraphQL arguments: {{args.myArgument}}
  """
  path: UrlTemplate!

  """
  Specifies which fields from the GraphQL selection to include in the response
  """
  selection: JsonTemplate!

  """
  Configuration for the request body, can include static values or
  selections from the GraphQL arguments
  """
  body: Body = { selection: "*" }
) on FIELD_DEFINITION

scalar JSON

"""
Body input type defines how to construct the request body for REST API calls.
It allows for dynamic construction from GraphQL arguments or static values.
"""
input Body {
  """
  Specifies which GraphQL arguments to include in the request body.
  Use "*" to include all arguments, or provide specific field names.
  """
  selection: InputValueSet

  """
  Static JSON content to include in the request body,
  which will be merged with any selected values.
  """
  static: JSON
}

"""
HttpMethod enum represents the standard HTTP methods supported
for REST API interactions.
"""
enum HttpMethod {
  """
  HTTP GET method for retrieving resources
  """
  GET
  """
  HTTP POST method for creating resources
  """
  POST
  """
  HTTP PUT method for replacing resources
  """
  PUT
  """
  HTTP DELETE method for removing resources
  """
  DELETE
  """
  HTTP HEAD method for retrieving headers only
  """
  HEAD
  """
  HTTP OPTIONS method for describing communication options
  """
  OPTIONS
  """
  HTTP CONNECT method for establishing tunnels
  """
  CONNECT
  """
  HTTP TRACE method for diagnostic testing
  """
  TRACE
  """
  HTTP PATCH method for partial modifications
  """
  PATCH
}