はじめに
GraphQLはAPI向けに作られたクエリ言語で、REST APIと比較して、取得するデータをクライアント側で詳細に制御でき、効率良くデータ取得できることで注目されています。
2023年にIBMが買収したStepZenは、迅速なGraphQL APIの開発を可能にするGraphQLサーバー環境を提供します。
この記事では、StepZenの無償版を使用してサンプルGraphQLをデプロイしてAPI呼び出しをするまでの手順を紹介します。
無償版では主に以下の制限があります。
- 300k calls/month
- デプロイできるエンドポイントは2つまで
- StepZen Cloudへのデプロイのみ可能
事前準備
StepZenのホームページより、メールアドレスを登録してアカウントを作成します。
GraphQLの作成
基本的には画面の指示通りに進めることで簡単にはじめることができます。
Step 1. Select Backend
バックエンドとして接続するデータソースを選択します。
ここでは、All Connectorsにある「GraphQL」を選択します。All Connectorsのいずれかを選択すると「Step2 Configuration」はスキップされます。
Step 3. Setup StepZen
StepZen CLIをインストールしてアカウント認証をします。
npmでStepZen CLIをインストールします。
npmが未インストールの場合は、先にnpm (Node.js) をインストールする必要があります。
https://nodejs.org/en/download
~ % npm install -g stepzen
added 284 packages, and audited 285 packages in 15s
38 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
npm notice
npm notice New major version of npm available! 8.19.3 -> 9.6.5
npm notice Changelog: https://github.com/npm/cli/releases/tag/v9.6.5
npm notice Run npm install -g npm@9.6.5 to update!
npm notice
インストールされたstepzenのバージョンを確認します。
~ % stepzen version
stepzen/0.29.0 darwin-arm64 node-v18.13.0
You are using the latest version.
StepZenアカウントでログインします。
ログイン時にAdmin Keyが求められるのでGUIよりコピペします。
~ % stepzen login -a travilah
What is your admin key?: *******************************************************************************************
You have successfully logged in with the travilah account.
Step 4. Build your endpoint
GraphQLエンドポイントを構成します。
任意のディレクトリーを作成し、StepZenワークスペースとしてinitializeします。
~ % mkdir stepzen
~ % cd stepzen
stepzen % stepzen init --endpoint=api/getting-started
Created a StepZen workspace in /Users/jiszk/stepzen
homeディレクトリーをワークスペースに使用することはできません。
~ % stepzen import graphql
› Error: Could not create a StepZen workspace in the current directory.
› Using the home directory as a StepZen workspace is not supported. Please select a different directory.
サンプル(getting-started)のGraphQLのスキーマをインポートします。
stepzen % stepzen import graphql
? What is the GraphQL endpoint URL? https://graphqldd.stepzen.net/api/dd1cf47f51ac830fe21dc00ec80cee65/__graphql
? Prefix to add to all generated type names (leave blank for none)
? Add an HTTP header, e.g. Header-Name: header value (leave blank for none)
Starting... done
Successfully imported graphql data source into your GraphQL schema
インポートしたGraphQLのスキーマをデプロイします。
stepzen % stepzen start
Deploying api/getting-started to StepZen... done in 2.5s 🚀
✓ 🔐 https://travilah.stepzen.net/api/getting-started/__graphql
✓ 🔐 wss://travilah.stepzen.net/stepzen-subscriptions/api/getting-started/__graphql (subscriptions)
You can test your hosted API with curl:
curl https://travilah.stepzen.net/api/getting-started/__graphql \
--header "Authorization: Apikey $(stepzen whoami --apikey)" \
--header "Content-Type: application/json" \
--data-raw '{
"query": "query SampleQuery { __schema { description queryType { fields {name} } } }"
}'
Or explore it with GraphiQL at
https://dashboard.stepzen.com/explorer?endpoint=api%2Fgetting-started
The StepZen Dashboard at dashboard.stepzen.com is the new default way to
explore your GraphQL APIs. You can use the --dashboard=local flag to start
a locally running GraphiQL instead.
Watching ~/stepzen for changes...
デプロイしたGraphQLの確認
StepZen Explorer
ダッシュボードのStepZen Explorerを使用してGraphQLのテストが可能です。
StepZen Explorerの詳細は以下を参照してください。
The StepZen Explorer
Test and query your GraphQL API deployed to StepZen from the dashboard.
ダッシュボードにアクセスします。
ダッシュボードのURLはstepzen start実行時に表示されます。
https://dashboard.stepzen.com/explorer?endpoint=api%2Fgetting-started
Builderタブでクエリを作成し、実行ボタンでクエリを実行します。
スキーマ内で使用可能なクエリのリストはDocsタブで確認することができます。
ここでは、例として1ドルを円換算した結果を取得するクエリを実行してみます。
curl
同様のクエリをcurlを使用して、graphql形式とjson形式の2パターンで実行してみます。
AuthorizationヘッダーにはStep. 3で提示されるAdmin Keyを指定します。
graphql形式
~ % curl -i -X POST 'https://travilah.stepzen.net/api/getting-started/__graphql' \
-H 'Authorization: apikey travilah::stepzen.io+1000::4ac3b69d000bae20e7f2d9a1b9249fc20a0f459b...' \
-H 'Content-Type: application/graphql' \
--data '{frankfurter_convertedAmount(amount: 1, from: "USD", to: "JPY")}'
HTTP/2 200
content-type: application/json; charset=utf-8
stepzen-trace: e9c5932306df684c0e777e4a9372541f
strict-transport-security: max-age=63072000; includeSubDomains; preload
vary: Origin
x-content-type-options: nosniff
date: Tue, 09 May 2023 14:10:48 GMT
content-length: 57
via: 1.1 google
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
{
"data": {
"frankfurter_convertedAmount": 135.14
}
}%
json形式
~ % curl -i -X POST 'https://travilah.stepzen.net/api/getting-started/__graphql' \
-H 'Authorization: apikey travilah::stepzen.io+1000::4ac3b69d000bae20e7f2d9a1b9249fc20a0f459b...' \
-H 'Content-Type: application/json' \
--data '{"query": "{frankfurter_convertedAmount(amount: 1, from: \"USD\", to: \"JPY\")}"}'
HTTP/2 200
content-type: application/json; charset=utf-8
stepzen-trace: a236f402a9d758f1d4ee92f92af2c9ba
strict-transport-security: max-age=63072000; includeSubDomains; preload
vary: Origin
x-content-type-options: nosniff
date: Tue, 09 May 2023 14:27:28 GMT
content-length: 57
via: 1.1 google
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
{
"data": {
"frankfurter_convertedAmount": 135.14
}
}%
以上、StepZenの無償版で簡単にサンプルGraphQL(getting-started)を作成して実行することができました。