GraphQL

blog 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 application/json, and all responses from the GraphQL endpoint will be returned with the Content Type application/json. The blog GraphQL API is spec compliant.

GraphQL Endpoint
https://blog.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://blog.gadget.app/api/graphql/playground. It's handy for exploring the blog GraphQL schema and supports handy features like autocomplete, saved queries, and pretty output formatting.

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(
10 response.data.gadgetMeta.name
11);
12// => blog

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: GraphQLJSONObject

JSON fields are used for JSON objects (key value pairs) only, and won't accept arrays or scalars.

Any

GraphQL Type: GraphQLJSON

Any fields are used to store anything and will accept objects, arrays, scalars including strings and numbers, and nested combinations of these.

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.