Get Started

The best way of getting started with the HostDesign web API is some hands on time with our API explorer. This'll introduce you to some graphql concepts and familiarise you with the possibilities of the API itself.

If you have something specific in mind that you want to build, you can have a look at the tutorials to see if it's covered there.

Once you're ready to build, you're ready to get authenticated and make calls from your code.

Exploring the API

You can find an instance of GraphiQL (a web-based GraphQL IDE) at hostdesign.com/graphql. Your query is on the left, the result is in the middle, and the documentation explorer is on the right.

This is the best way to play around with and explore the API but be warned - this is production data and any changes you make here will be reflected on hostdesign.com.

The documentation explorer on the right lists all queries (for reading data) and mutations (for writing data) available to you, as well as all the arguments, fields and data types.

If you'd like to learn more about graphql, here's a good guide for getting started: graphql.org/learn

Authentication

Hostdesign uses OAuth access tokens for authentication.For local development or internal scripts you can generate a personal access token at /oauth/devtoken. Otherwise refer to the authentication page.

Making calls from your code

The Hostdesign API works entirely over HTTP. To make an API call from your own code, you must send a POST request to our graphql endpoint ( https://api.marvelapp.com/graphql/ ), with a Content-Type: application/json header and a json payload as the request body. The payload should at a minumum have a query key, which is your graphql query (or mutation) formatted as a string. If your queries make use of variables, you must send those up under the variables key

You'll also need to send an access token, as described in authenticating requests. Here's an example using curl:

Introspecting the schema

One of the GraphQL's benefits is that it's introspective, if you've ever used a poorly documented REST API you'll appreciate straight away the need for this. No more traipsing through incomplete or unmaintained docs, if you want to see the whole schema (the same data the GraphiQL sandbox uses to suggest / autocomplete), use the following query:

One of the GraphQL's benefits is that it's introspective, if you've ever used a poorly documented REST API you'll appreciate straight away the need for this. No more traipsing through incomplete or unmaintained docs, if you want to see the whole schema (the same data the GraphiQL sandbox uses to suggest / autocomplete), use the following query: