SendGridのAPIドキュメントが新しくなったので遊んでみた
先日、SendGridのドキュメントに新しいAPIドキュメントが追加されました。元々、APIリファレンスに相当するドキュメントは存在していたのですが、StopLightというサービスの機能を使ってより使いやすく整理した、といったところでしょうか。
入り口
新しいドキュメントの入り口はちょっとわかりづらくて、ドキュメントのトップページ上にある「SendGrid API」というリンクです。
主な特徴
次に、この新しいAPIドキュメントの特徴をまとめてみます。リクエストとレスポンスがちゃんと定義された
今まで定義されてなかったのかよ、って感じですが、これまではリクエストについては概ね定義されていましたが、レスポンスはほとんど定義されていませんでした。レスポンスの例は載っていたので特に不都合はなかったのですが、ちゃんとした定義があるに越したことはありませんね。
Swagger(OAS)/RAMLによる定義が公開された
StopLightの機能の一つですが、APIの定義全体がSwagger形式とRAML形式で公開されています。これがあると、SendGridのAPIサーバのモックを作ってテストに利用するといったことができるようになります。
APIドキュメントからリクエストのテストができるようになった
これもStopLightの機能の一つのようですが、各エンドポイントのページの「Try it out」タブを選択するとドキュメントからAPIのリクエストを送信して結果確認ができます。使い方はとても簡単で、必要なパーミッションを持ったAPIキーをYOUR_API_KEYパラメータに設定、リクエストJSONをBodyに指定して「SEND REQUEST」ボタンを選択するだけです。
コード生成ができるようになった
「Try it out」でリクエストを送信すると、代表的な言語のコード生成ができるようになります。「Code Generation」から一通りのプログラミング言語およびコマンドのサンプルコードが確認できるので、サッとコピペして使えます。
PostmanにSwaggerの定義ファイルを喰わせてみる
Swaggerの定義が公開されたということは、これを元に様々なAPI連携ツールが利用できることを意味しています。例えば、みんな大好きPostmanにインポートすると、各エンドポイントのリクエスト設定が一括でPostman上に取り込めるので、これをベースにコピーしたり編集したりして色々な条件でリクエストを試すことができます。
まず、Postmanを起動して「Import」ボタンを選択します。
次に、「Import From Link」を選択してSwagger定義のURLを貼り付けて「Import」ボタンを選択します。
しばらく待つと画面左側に一通りのAPIリクエスト設定が表示されます。また、認証情報はAuthorizationという変数を参照するようになっているので、Authorization変数に「Bearer APIキー」を設定するとそのままリクエストが送れるようになります。
以上、SendGridの新しいAPIドキュメントで遊んでみました。
コメント
コメントを投稿