Content API requests were all accepted via POST (as detailed in the
GraphQL spec) and not amenable to caching.
Now, requests are also accepted via GET (as optionally allowed for query
requests only), and cached.
Also sent the request method to Logflare so we can track the ratio of
GET/POST requests.
* feat(content api): add error endpoint
Add an endpoint to return the details of a Supabase error, given the
error code and service.
Schema additions:
```graphql
type RootQueryType {
"...previous root queries"
"""Get the details of an error code returned from a Supabase service"""
error(code: String!, service: Service!): Error
}
"""An error returned by a Supabase service"""
type Error {
"""
The unique code identifying the error. The code is stable, and can be used for string matching during error handling.
"""
code: String!
"""The Supabase service that returns this error."""
service: Service!
"""The HTTP status code returned with this error."""
httpStatusCode: Int
"""
A human-readable message describing the error. The message is not stable, and should not be used for string matching during error handling. Use the code instead.
"""
message: String
}
enum Service {
AUTH
REALTIME
STORAGE
}
```
* test(content api): add tests for top-level query `error`
Add a top-level field to search docs globally. Right now this only
returns Markdown guides (not references, GitHub discussions, or partner
pages.
The full GraphQL schema at this point:
```
schema {
query: RootQueryType
}
type RootQueryType {
"""Get the GraphQL schema for this endpoint"""
schema: String!
"""Search the Supabase docs for content matching a query string"""
searchDocs(query: String!, limit: Int): SearchResultCollection
}
"""A collection of search results containing content from Supabase docs"""
type SearchResultCollection {
"""A list of edges containing nodes in this collection"""
edges: [SearchResultEdge!]!
"""The nodes in this collection, directly accessible"""
nodes: [SearchResult!]!
"""The total count of items available in this collection"""
totalCount: Int!
}
"""An edge in a collection of SearchResults"""
type SearchResultEdge {
"""The SearchResult at the end of the edge"""
node: SearchResult!
}
"""Document that matches a search query"""
interface SearchResult {
"""The title of the matching result"""
title: String
"""The URL of the matching result"""
href: String
"""The full content of the matching result"""
content: String
}
```
Towards DOCS-214
* feat (content api): add top-level schema query
Adds a top-level schema query that returns the stringified GraphQL
schema for this endpoint. Useful for LLMs to access the stringified
schema for prompting and tool calls.
Query shape:
```
query Search {
schema
}
```
Query response:
```
{
"data": {
"schema": "schema {\n query: RootQueryType\n}\n\ntype RootQueryType
{\n \"\"\"Get the GraphQL schema for this endpoint\"\"\"\n schema:
String\n}"
}
}
```
Towards DOCS-214
* test (content api): add schema snapshot
Add schema snapshot test to prevent unintentional changes to public API
for this endpoint
* fixup! feat (content api): add top-level schema query
* fix (content api): local dev introspection
The validation rules that are used for security in production are
preventing GraphiQL from introspecting the schema in dev. Since this DX
feature is incredibly useful, I'm turning off the complexity and depth
validations for dev GraphiQL only. Local curls, etc., will still have
production-standard validation so it can be tested locally.
GraphQL errors were occasionally returned as normal HTTP status code
errors, switched to using only GraphQL-spec compliant errors for the
/docs/api/graphql endpoint.
The first PR in a series to build out the Content API. Adds a dummy
GraphQL route with some tests: for now all this does is validate the
request body and return a 404.
