Introduction

StepZen's online JSON2SDL tool allows you to paste in JSON and copy out SDL:

This tooling makes it a lot easier to layer your own GraphQL APIs over REST services. Instead of poring over the REST responses and manually writing out each type and field in a GraphQL Schema Definition Language, you can make a few clicks and have an inferred schema at the ready. It relies on StepZen's introspection service to make the transformation. Let's take a closer look.

Example: Spotify API

Let's say you were working with the Spotify API. You want to create artist profile pages for an online music journal. You know the developers working on the user interface will want to use a GraphQL request to get the required artists by their ids. You also know they have used StepZen to create a GraphQL layer to connect the website with their CMS.

They will want to coordinate artist profile with images for their CMS, so when we bring in the Spotify API, we want to connect to this GraphQL API layer. The problem? Spotify uses a REST API.

Time to break out your GraphQL skills! Normally, you'd be scanning the lines of JSON from the Spotify documentation, deciding how to write your type for the schema:

{
  "external_urls": {
    "spotify": "string"
  },
  "followers": {
    "href": "string",
    "total": 0
  },
  "genres": ["Prog rock", "Grunge"],
  "href": "string",
  "id": "string",
  "images": [
    {
      "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
      "height": 300,
      "width": 300
    }
  ],
  "name": "string",
  "popularity": 0,
  "type": "artist",
  "uri": "string"
}

But with the JSON2SDL tool, a simple copy/paste results in:

type External_urls {
  spotify: String
}

type Followers {
  href: String
  total: Int
}

type Image {
  height: Int
  url: String
  width: Int
}

type Root {
  external_urls: External_urls
  followers: Followers
  genres: [String]
  href: String
  id: String
  images: [Image]
  name: String
  popularity: Int
  type: String
  uri: String
}

All it needs now is a bit of personalization, a query, and it's ready to go into your sdl file:

type spotify_External_Urls {
  spotify: String
}

type spotify_Followers {
  href: String
  total: Int
}

type spotify_Image {
  height: Int
  url: String
  width: Int
}

type spotify_Artist_For_ArtistsByIDList {
  external_urls: External_urls
  followers: Followers
  genres: [String]
  href: String
  id: String
  images: [Image]
  name: String
  popularity: Int
  type: String
  uri: String
}

type Query {
  spotify_ArtistsByIDList(spotify_token: Secret!, ids: String): Spotify_Artists
    @rest(
      endpoint: "https://api.spotify.com/v1/artists?ids=$ids"
      headers: [{ name: "Authorization", value: "Bearer $spotify_token" }]
    )
}

Done. No worries about getting nested objects correctly translated or types mismatched. Your schema is ready to be consumed in the frontend!

If you want to add documentation to your SDL after this step, StepZen can help you do that in a low-code way as well.

We'd love to see what you do with the JSON2SDL tool. Let us know in Discord!