こんにちは。株式会社 PHONE APPLI リサーチデベロップメント の松井です。
この記事では、Postman を使って PHONE APPLI API (v1.2) にリクエストする方法を紹介します。
- PHONE APPLI API とは？
- Postman とは?
- 初期セットアップ
- 実際にリクエストしてみる
- 社内連絡先一覧を取得する
- 条件に一致する社内連絡先を調べる
- 部署一覧を取得する
- 社内連絡先を編集する
- 最後に
- PHONE APPLIについて
PHONE APPLI API とは？
組織を強くするコミュニケーションポータルである「PHONE APPLI PEOPLE」のデータ入出力を行える RESTful API です。
Postman とは?
API の構築やテストなどが行える API プラットフォームです。
Postman はデスクトップアプリケーションと Web アプリケーションが用意されているため用途に応じて使い分けることができ、とても便利です。
初期セットアップ
リクエストを送信するためには Postman と PHONE APPLI API の初期セットアップが必要なため、まずはその方法の説明から始めていきます。
STEP① Postman にサインアップ
- 以下のページから、Postman にサインアップ。
identity.getpostman.com - 自身の名前と役職、他の人を招待するかどうかの質問に回答。
- 回答が完了すると、自動的に Postman の Web アプリケーションに遷移。
STEP② My Workspace を開く
・サインアップ後、自動的に Postman の My Workspace に遷移している場合
このステップはスキップ。
・Postman の Home ページに遷移している場合
ページ上部の Workspaces タブから My Workspace を選択し、開く。
STEP③ New Collection を作成
- 左サイドバーから Collections を選択。
- ＋ボタンをクリックして、コレクションを作成。
STEP④ API キーの取得
STEP⑤ API キーの設定
- 作成されたコレクション
New Collectionを選択。 - Authorization タブを開く。
- Type を
API Keyに設定。 - Key として
X-Pa-Api-Keyを設定。 - Value として、
⑤の工程でコピーしておいた API キーを設定。 - Add to は
Headerを指定。
- Ctrl + S (command + S) で設定を保存。
STEP⑥ 環境変数にベースとなる URL を設定
- コレクションの Variables タブを選択。
- VARIABLE に変数名
base_url(変数名はなんでもOK) を入力。 - INITIAL VALUE に
https://api.phoneappli.net/v1を入力。
(Sandbox 環境の場合は、https://api-sandbox.phoneappli.net/v1を入力。)
- Ctrl + S (command + S) で設定を保存。
環境変数を設定しておくことで、ベースとなる URL を「{{変数名}}」の形式で入力できるようになります。
そのため、次のようにURLの見た目を簡潔にすることができます。
環境変数なし: https://api.phoneappli.net/v1/test?param=12345
環境変数あり: {{base_url}}/test?param=12345
STEP⑦ 新しい Request を作成する
Postman の Request の作成方法は、コレクション内で初めて Request を作るかどうかで方法が異なるため、２種類の方法を説明します。
コレクション内で "初めて" リクエストを作成する場合
- 作成したコレクションを選択。
- "This collection is empty Add a request to start working." と表示されるので、
"Add a request" をクリックしてリクエストを作成。
コレクション内で "別の新しい" リクエストを作成する場合
- New Collection にカーソルをホバーし、ミートボールメニュー(点が三つのアイコン)をクリック。
- Add request を選択し、新しいリクエストを作成。
✅ 初期セットアップはこれで完了です。
実際にリクエストしてみる
リクエストの結果は、Response 欄に JSON 形式で表示されます。
リクエストに失敗した場合は以下のドキュメントを参照し、エラーの内容を確認してください。
[Document] PHONE APPLI API エラーレスポンス: developer.phoneappli.net
社内連絡先一覧を取得する
[Document] PHONE APPLI API 社内連絡先一覧取得: developer.phoneappli.net
- リクエスト方法を
GETに設定し、URL 欄に{{base_url}}/usersを入力。
- Send ボタンを押す。
条件に一致する社内連絡先を調べる
名前に「山田」が含まれる社内連絡先を調べる方法 (２種類)
- URL 欄に直接入力
{{base_url}}/users?fullname=山田 - Params タブに入力
部署一覧を取得する
[Document] PHONE APPLI API 部署一覧取得: developer.phoneappli.net
- リクエスト方法を
GETに設定し、URL 欄に{{base_url}}/divisionsを入力。
- Send ボタンを押す。
名前に「山田」が含まれ、営業部署に所属している社内連絡先を調べる方法(２種類)
前提として、部署一覧取得で部署識別番号を入手しておく。
[例] 営業部署の部署識別番号を 1234 とする
- URL欄に直接入力
{{base_url}}/users?fullname=山田&divisionIds=1234 - Params タブに入力
社内連絡先を編集する
[Document] PHONE APPLI API 社内連絡先編集: developer.phoneappli.net
前提として、社内連絡先一覧取得で userId を取得しておく。
[例] 編集したい社内連絡先の userId を 456789 とする
- リクエスト方法を
PATCHに設定し、URL 欄に{{base_url}}/users/456789を入力。 - Body タブを開く。
- タイプを
rawに設定。 - フォーマットを
JSONに設定。 - 設定したい項目名と、書き換え後の値を次のように入力。
{
"設定したい項目名": "書き換え後の値"
}
[例] コメントを「あいうえお」にしたい場合)
6. Send ボタンを押す。
最後に
Postman は API リクエスト機能だけでなく、コレクションのエクスポート/インポート機能など様々な便利機能が他にもあるので是非使ってみてください！
以上、『 Postman を使って PHONE APPLI API (v1.2) にリクエストするには？ 』でした！
