Consuming the Deepgram API: The GraphQL Edit

Lucia Cerchie - Jun 10 '22 - - Dev Community

In this project, we’ll explore how to use Deepgram, StepZen, and Next.js to convert the Deepgram REST API into your own GraphQL API, translate audio to English and French text, and display the result in a user interface.

  • Deepgram’s REST API - A speech-to-text API built on a 100% deep learning platform. It offers up to 90% translation accuracy with model training with no human validation necessary. I chose to write about it because the developer experience is excellent; should you want to extend the capabilities of this API further, you’ll find exactly what you need in Deepgram’s docs and tutorials.
  • StepZen’s REST2GraphQL tool - A user interface designed to convert your REST APIs to GraphQL, no code necessary. StepZen introspects the endpoint, generates a schema, and deploys your GraphQL endpoint once you hit ‘Generate’. These endpoints are public and are available for you to use and share for 30 days. To take the schema you’ve created with REST2GraphQL and create a private, scalable endpoint for it, sign up for a StepZen account.
  • Next.js - A React framework providing features like Server Side Rendering. We’ll use it in this tutorial to fetch the data from our GraphQL endpoint. That way, you’ll learn how to safely send an API key on a server-side request.

Converting the Deepgram REST API to GraphQL

The first thing we’ll learn is how to use REST2GraphQL to convert Deepgram to a GraphQL API.

Access the tool at rest2graphql.io

Then, select ‘POST’ and enter the Deepgram ‘listen’ endpoint we’ll be using:

rest2graphql http method selector

Next, you’ll add some query parameters.

Deepgram uses these parameters to determine the language to translate, the model to use, and whether to punctuate the text. They are sent to StepZen on ‘Generate’, and StepZen creates a GraphQL schema with query variables matching these parameters.

rest2graphql params selector

You’ll also need to add your Deepgram API key under the Headers tab to get access to your Deepgram endpoint. You can find the steps to create a Deepgram API key in the Deepgram docs.

rest2graphql headers selector

Now, click Generate, and your endpoint is deployed! Query it in the browser with GraphiQL, or customize the values of your request’s variables with the ‘Query Arguments’ widget.

screenshot of deployed endpoint in interface

Consuming the GraphQL API in a Next.js App

Next, let’s look at how to consume your GraphQL endpoint in a Next.js app. I’ll show snippets to illustrate my steps, so here’s the Github repository if you’d like to clone the entire code.

I started by creating a Next.js app. Then, I created a getServerSideProps function to feed the data into the Home component, inside pages/index.js .

export async function getServerSideProps(context) {

}

export default function Home(props) {
    return (
        <div className={styles.container}>
            <Head>
                <title>Create Next App</title>
                <meta
                    name="description"

ETC...
Enter fullscreen mode Exit fullscreen mode

I wrote my fetch call inside the getServerSideProps function. called the endpoint generated by REST2GraphQL, https://public6ddcc5208696d858.stepzen.net/api/deepgram/__graphql, sent the headers required by the Deepgram API, and sent my GraphQL query as the body (you can check out the generated JavaScript boilerplate to see the query that I copied).

I protected the apikey by saving it in my env. file. For information about how to use the fetch API with GraphQL, view StepZen’s documentation.

const apikey = process.env.DEEPGRAM_APIKEY

const res_in_en = await  fetch('https://public6ddcc5208696d858.stepzen.net/api/deepgram/__graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Token ${apikey}`,
  },
  body: JSON.stringify({
    query: `
    query deepgramQuery($authorization: String!, $language: String, $model: String, $punctuate: String, $url: String) {
        deepgramQuery(
          authorization: $authorization
          language: $language
          model: $model
          punctuate: $punctuate
          url: $url
        ) {
          results {
            channels {
              alternatives {
                confidence
                transcript
                words {
                  confidence
                  end
                  punctuated_word
                  start
                  word
                }
              }
            }
          }
        }
      }
      `,
    variables: {
        url: 'https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav',
        language: 'en-US',
        model: 'general',
        punctuate: 'true',
        authorization: `Token ${process.env.DEEPGRAM_APIKEY}`
    },
  }),
})
Enter fullscreen mode Exit fullscreen mode

After making the call in the function, we transform the result into JSON and return it as props:

const en_data = await res_in_en.json()

    if (!en_data) {
        return {
            notFound: true,
        }
    }

    return {
        props: { en_data }, // will be passed to the page component as props
    }
Enter fullscreen mode Exit fullscreen mode

Next, I surfaced the data text on the homepage by using the props passed from the getServerSideProps function to the Home component (something Next will do automatically here).

<h1>DeepGram Samples</h1>
     <h2>English Sample</h2>
         <p>
           {
     props.en_data.data.deepgramQuery.results.channels[0].alternatives[0].transcript
            }
         </p>
Enter fullscreen mode Exit fullscreen mode

After that, I can see it rendered in my localhost endpoint!

screenshot of rendered English text

French Sample

So now I’d created an English sample… how about another language? Deepgram has support for 18 languages! Let’s try French. The first thing is to repeat the 'Converting the Deepgram REST API to GraphQL' process outlined above, but with a ‘fr’ value for the language parameter rather than ‘en-US’.

I also used a French sample hosted at https://www.lightbulblanguages.co.uk/resources/audio/quelageastu.mp3. I then created a similar query and passed the result of it to props as well. You can see my final version in the Github repository, or give it a go on your own!

screenshot of rendered french text

Where to Go From Here

In this post, you learned how to convert Deepgram’s API to GraphQL with StepZen, then consume it in a Next.js app. To learn more about these technologies:

We hope you enjoy building your own project with StepZen; please know we’d be happy to help you learn more! Jump into our Discord server to ask a question.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .