Postman ブルーバッジ WorkSpaces でAPIのクイックスタート OpenAPI編

Postmanには特定サービスのAPIコールがまとめてサンプルやドキュメントと合わせてセットになっているワークスペースを作成し公開する機能が備わっています。

この機能を用いて作成したワークスペースをPostmanに申請して認定されるとブルーバッジが付与されます。ブルーバッジが付与されたワークスペースは、対象となるサービスにおけるAPIの使い方を学ぶクイックスタートとして強力に機能します。

このブルーバッジ認定を取得しているワークスペースは、日本ではFreeeさんなどが存在していますが、Postman側で作成したものと各サービス提供者が作成したものが存在しています。

今日はPostmanが作成したOpenAI用ワークスペースをもとに、以下に初めてのAPIコールを成功させるまでの手順＆学習コストが短縮化されるか、を見ていきたいと思います。

用意する物

OpenAIのAPIトークン
こちらは本記事の内容からは割愛しますが、以下の記事がよくまとまっていました。
https://qiita.com/kurata04/items/a10bdc44cc0d1e62dad3
この手順に基づき、sk-projから始まる文字列をコピーしておきます。

さっそくやってみる

まずPostmanのコンソール上部でOpen AIで検索します。

ワークスペース、ブルーバッジの有無、作成者（Postman DevRel)が確認できます。

こちらを開いてフォークさせます。

コレクションをフォークをクリックします。

無事フォークされると自分のワークスペースにChatGPT APIが加わっているはずです。
この画面からAPIのドキュメントを読むことが出来、詳細が必要であればOpenAIのドキュメントページへのリンクが存在しています。

ここからPOST Chat Completionという一番簡単な質問を投げて回答をもらうAPIコールを実行していきます。

継承について

作業を進めるまえにPostman コレクションの継承について纏めます。
例えば上の図であればChatGPT API→ChatGPT API Use Cases→ChatGPT API Text Generation→POST Chat Completationとなっています。
当然下の階層に行けば行くほど複数の要素を含んでいます。

毎回同じ設定をしなくて済むように、再利用可能な設定であれば上位階層で設定しておけば済むのが 継承 です。
例えば最上位階層の認可タブでは先ほど取得したAPIトークンの設定が存在しています。ここにAPIトークンを入力して保存しておきます。

変数タブにはAPIコールに必要な様々なパラメータがあらかじめセットされています。

初めてOpenAIのAPIを使う場合、どのAPIコールにドのパラメータが必要なのか、その値は何であるべきなのか、Bodyで渡すのかHeaderで渡すのか、等学ぶことが多く時間がかかりますが、Postmanのブルーバッジワークスペースを使うことでこれらがあらかじめ動作するサンプルとして提供されるのがメリットです。
実際のAPIコールの認可タブを見てみると上位の認可設定を継承と表示されています。

ドロップダウンから値を変更することで継承を行わず、特定APIコールのみ別の値を設定することも可能です。

ボディのタブにはあらかじめ継承された２つの変数がセットされているため、APIのテスト呼び出しをすぐ行うことが可能です。継承された値は変数としてセットされていますが、これを固定文字列に切り替えることで専用APIコールのテストにすぐ切り替えることが出来ます。

送信ボタンを押して実行すると以下のレスポンスが戻るはずです。

{
    "id": "chatcmpl-AZBKo7axpzqMXXrMbY6OahoGrwSwD",
    "object": "chat.completion",
    "created": 1732948414,
    "model": "gpt-4o-2024-08-06",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "The 2020 World Series was played at Globe Life Field in Arlington, Texas. This was part of a neutral-site format due to the COVID-19 pandemic.",
                "refusal": null
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 53,
        "completion_tokens": 33,
        "total_tokens": 86,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "audio_tokens": 0
        },
        "completion_tokens_details": {
            "reasoning_tokens": 0,
            "audio_tokens": 0,
            "accepted_prediction_tokens": 0,
            "rejected_prediction_tokens": 0
        }
    },
    "system_fingerprint": "fp_831e067d82"
}

スクリプトタブのPost-Responseで戻ってきたResponseの修正が行えるのも便利な機能です。

pm.test("Response status code is 200", function () {
    pm.response.to.have.status(200);
});


pm.test("Content-Type header is application/json", function () {
    pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});


pm.test("Validate the choices array", function () {
    const responseData = pm.response.json();
    
    pm.expect(responseData.choices).to.be.an('array').that.is.not.empty;
    responseData.choices.forEach(function(choice) {
        pm.expect(choice).to.be.an('object');
        pm.expect(choice.index).to.exist.and.to.be.a('number');
        pm.expect(choice.message).to.exist.and.to.be.an('object');
        pm.expect(choice.finish_reason).to.exist.and.to.be.a('string');
    });
});


pm.test("Created field is a non-negative integer", function () {
    const responseData = pm.response.json();
    
    pm.expect(responseData.created).to.be.a('number').and.to.be.at.least(0);
});


pm.test("Model field should not be empty", function () {
    const responseData = pm.response.json();
    
    pm.expect(responseData.model).to.exist.and.to.not.be.empty;
});

同じようにヘッダータブにもあらかじめ必要なものがセットされています。

いかがでしょうか？新しいサービスのAPIを学ぶ際にドキュメントも一緒に読むことが出来き、サンプルAPIコールをすぐ実行できるブルーバッジワークスペース今日はご紹介しました。