GraphQL

Simple Blog Example uses GraphQL as a high performance API interchange language. GraphQL gives developers a straightforward way of asking for specific data from the API across the whole graph of related models for an application. The JavaScript API client provides helpers that let you read data or execute actions at a high level, but if you need to fetch a specific set of data, especially across relationships, executing one GraphQL query is a great way to do so.

Learn more about GraphQL at https://graphql.org/learn or https://www.howtographql.com/.

Connection Details

All requests to the GraphQL endpoint should be made with the Content-Type header set to application/json, and all responses from the GraphQL endpoint will be returned with the Content-Type response header set to application/json. The Simple Blog Example GraphQL API is spec compliant.

To make requests to the GraphQL API, use the following URL:

Development GraphQL Endpoint
https://simple-blog-example--development.gadget.app/api/graphql

To make requests to the GraphQL API, use the following URL:

Production GraphQL Endpoint
https://simple-blog-example.gadget.app/api/graphql

Developing using the GraphQL Playground

Gadget serves a web-based GraphQL request console for easy development of custom or complicated GraphQL queries at https://simple-blog-example.gadget.app/api/graphql/playground. It's handy for exploring the Simple Blog Example GraphQL schema and supports handy features like autocomplete, saved queries, and pretty output formatting.

Connecting with the Gadget JavaScript Client

Gadget generates a type-safe, high-quality npm package that can be used in front-end and back-end JavaScript projects for the Simple Blog Example API. Find instructions for setting up the API client on the Installing page.

Executing Queries

With a set up GadgetClient object, you can access data with the .query function. For more information on the return type of the .query method, consult the urql client.query docs.

.query returns a Promise for the data from the API in the same shape that the GraphQL query is written. The response object has the data at the data property.

JavaScript
1const response = await api.query(`
2 query GetAppName {
3 gadgetMeta {
4 name
5 }
6 }
7`);
8
9console.log(response.data.gadgetMeta.name);
10// => Simple Blog Example

Connecting with fetch

Gadget's GraphQL API can be used without any wrapper client library in JavaScript by using fetch.

JavaScript
1const result = await fetch(
2 "https://simple-blog-example--development.gadget.app/api/graphql",
3 {
4 headers: {
5 accept: "application/json",
6 "content-type": "application/json",
7 },
8 body: JSON.stringify({
9 query: `
10 query GetAppName {
11 gadgetMeta {
12 name
13 }
14 }
15 `,
16 }),
17 method: "POST",
18 }
19);

Gadget generally recommends using the provided API Client package where possible.

Connecting with cURL

Gadget's GraphQL API can be used from command line HTTP clients like cURL as well:

Shell
curl 'https://simple-blog-example--development.gadget.app/api/graphql' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
--data-raw '{"query":"query { gadgetMeta { name } }"}'

Why GraphQL?

GraphQL is a newer technology that has answers for many of the questions REST and SOAP don't. It allows developers to write high-performance code by asking for only the data needed for a specific use case, instead of having to execute multiple requests to access related data and waste time getting fields that aren't used. It provides some basic type checking and schema validation so that API consumers can rely on the returned data being stable and not breaking their applications over time. GraphQL also has a thriving ecosystem of tools that leverage the introspect-ability of GraphQL APIs like the API Playground, schema stitching tools, and more.

GraphQL types

Gadget maps Gadget field types to specific GraphQL types for easy consumption of rich data via the GraphQL API.

ID

GraphQL Type: GadgetGraphQLID

Custom GraphQL scalar representing Gadget ID values as strings.

String

GraphQL Type: GraphQLString

Boolean

GraphQL Type: GraphQLBoolean

URL

GraphQL Type: GraphQLURL or GraphQLString

Returns a custom GraphQLURL scalar if URL validation is turned on, and a string otherwise

Email

GraphQL Type: GraphQLEmailAddress or GraphQLString

Returns a custom GraphQLEmailAddress scalar if URL validation is turned on, and a string otherwise

Enum

GraphQL Type: [GraphQLString!]

Returns a list of strings

RichText

GraphQL Type: GraphQLRichText

Returns a custom object representing the rich text, with html, markdown and truncatedHTML fields for accessing the content in different ways

DateTime

GraphQL Type: GraphQLDate or GraphQLDateTime

Returns a full GraphQLDateTime if the Include Time option is on, and a GraphQLDate otherwise

Number

GraphQL Type: GraphQLInt or GraphQLFloat

Returns a GraphQLFloat if the allowed number of decimals is unset or greater than 0, and a GraphQLInt otherwise

JSON

GraphQL Type: GraphQLJSON

JSON fields are used to store valid JSON. Valid values can be objects, arrays, or scalars including strings and numbers.

Any

GraphQL Type: GraphQLJSON

Deprecated. Any fields act the same as JSON fields.

BelongsTo

GraphQL Type: <related object type>

Returns the GraphQL type for the related model.

HasOne

GraphQL Type: <related object type>

Returns the GraphQL type for the related model.

HasMany

GraphQL Type: <related object type>Connection

Returns a Relay style Connection interface for accessing the list of related records. The connection has the pageInfo and edges properties.

HasManyThrough

GraphQL Type: <related object type>Connection

Returns a Relay style Connection interface for accessing the list of related records. The connection has the pageInfo and edges properties.

Required

All of the Gadget GraphQL types are governed by the Required option, which marks them as not null in the GraphQL API's accepted inputs and returned data. Changing the Required-ness of a field in the Gadget Editor will reflect in the GraphQL API immediately.