最近 Postman のチュートリアルを触っていて、改めてその素晴らしさに感動したので、もっと Postman を触ってくれる人が増えてほしいなーと思いまして Web API 初心者向けの Postman 記事を書いてみました。

（以下の画像は衝動的に空輸してしまった私のPostman Tシャツです）

一応この記事は「#7 はじめてのIT勉強会 in 仙台(2019)」でのLT用登壇資料ベースとして書いているので、後々スライドや登壇時の動画も公開するかなーと思っています。

lets-go-study-meeting.connpass.com

この記事は誰に向けて？
Postman って何？
Postman の入手方法
Web API を使うために把握するべき７つの要素（REST Likeなもの向け）
- Base URI
- Resource
- Method
- Query
- Header
- Body
- Authentication
Postman を使って O'Reilly BookList の Web APIを叩いてみよう
それでもわからない？ API Network でリクエストのためのテンプレートを手に入れよう
Postman API Network に無いものはどうすればいいの？　OpenAPI（Swagger）を取り込んでみよう
APIリクエストはできた。でも、その後プログラムからはどうすればいいの？
おわりに

この記事は誰に向けて？

前述の通りこれははじめて Web APIを触ってみようと言う方向けに書いています。Web APIというものを聞いたことがあるけれど、イマイチ一歩踏み出せない。触り始めるためにどうしたらいいのかわからない。そんな方に Postman というツールをきっかけにして踏み出してもらおうという趣旨です。

あまり Web APIとはなんぞや？　みたいなところには突っ込みすぎません。Web APIのドキュメントは見たことあるけれど、ここからどうしたらいいのかわからない、という感じのところで読むと良いと思います。

Postman って何？

Postman は Web APIの開発者「提供する側・活用する側」双方にとってよりよい開発エクスペリエンスを提供するクライアントアプリケーションです。

最近は Web API開発者のためのコラボレーションプラットフォームとも呼ばれていますね。

www.getpostman.com

f:id:sugimomoto:20191022145642p:plain

大まかな機能は大別して、下記の6種類提供されています。

API Client：公開されているもしくは開発中の各種APIを簡単にテストできる機能です。
Automated Testing：API開発者向けに各エンドポイントに対する自動テスト機能を提供します。
Design & Mock：APIを開発するにあたって、API SchemaをDesignするための専用EditorとそれをテスティングするためのMock Server機能を提供します。
Documentation：PostmanのAPI定義から自動的にAPIドキュメントを生成し、外部ユーザーに提供することができる機能です。
Monitors：提供されているAPIを定期的にチェックし、APIのアップデートや変更に伴う破損や従来のエクスペリエンスに変化が無いかモニタリングすることができます。
Workspaces：チームでAPIを共同開発するためのコラボレーション機能を提供します。

f:id:sugimomoto:20191022145648p:plain

なお、今回は Postman のコア機能とも言える「API Client」に焦点を絞って紹介します。

Postman の入手方法

Postman はもともとGoogle Chrome の拡張機能として提供されていましたが、現在は各プラットフォーム（Windows版、macOS版、Linux版）のクライアントアプリとして提供されています。

以下のURLからダウンロードして、インストールします。

https://www.getpostman.com/downloads/

f:id:sugimomoto:20191022145655p:plain

私はもっと挑戦的に生きたいんだ！　という方は将来的に正式リリースが予定されている機能を試すことができるCanary版をダウンロードしましょう。

https://www.getpostman.com/downloads/canary

f:id:sugimomoto:20191022145701p:plain

Web API を使うために把握するべき７つの要素（REST Likeなもの向け）

さて、それでは早速 Web APIを試してみたいと思いますが、その前に何を把握すれば Web APIを実行できるのか、事前に把握するべき重要な要素を確認します。

今日 Web APIはRESTという設計思想に（幾分か）則って公開されているものが多数を占めます。各プラットフォーマー・Web API提供者側でちょっとづつニュアンスが異なる部分もあるでしょうが、とりあえず「これさえ抑えておけば怖くない。Web APIを触るための７つの要素」があると思って大丈夫でしょう。

Base URI
Resource
Method
Query
Authentication
Header
Body

なお、今回は私が公開している O'Reilly Book List APIをベースとして紹介します。

CData API Server（https://t.co/oE8WxzNf5J）を使って1分くらいで作ったO'Reilly Book List APIを公開してみました。https://t.co/7BziYVLMot
ID：user（ReadOnly）
Password：3s3E4a4r7Q7d2a1J0i4l
AuthType：Basic

Azure WebApps 格安プランなので、あまりにアクセスがあると落ちちゃうかも。 pic.twitter.com/7Nzn0gjWHk
— Kazuya Sugimoto (@sugimomoto) October 16, 2019

ちなみにこの Web APIの作り方はこちらで書いています。

kageura.hatenadiary.jp

Base URI

一番最初に知らなければいけないことは、Web APIを提供しているサービサーのURIエンドポイントを特定することです。

今回のWeb APIでは以下のエンドポイントURIが対象になります。

f:id:sugimomoto:20191022145710p:plain

APIによっては、ここにバージョン名などが含まれる場合があります。

例えば Qiita API の場合は以下のように「v2」というバージョンが入ります。ここまでをベースとなるエンドポイントURIと今回は見なしていいでしょう。

https://qiita.com/api/v2/items

Resource

Web API ではどんなデータを操作するのかを決める必要があります。Twitterであれば、ツイートやいいね、Qiitaであれば記事やチームなど。それを先程のBase URIと合わせて指定するのがWeb API（REST）では一般的です。

今回の Web APIでは以下のOReillyBookListがResourceにあたります。

f:id:sugimomoto:20191022145719p:plain

（実は設計思想的にはあまりよくない・・・。）

Qiita APIでいくと、以下の「items」がResourceです。このitemsに対してなんらかの操作をしますというのが、指定のイメージです。

https://qiita.com/api/v2/items

また、エンドポイントによっては以下のように、リソースをネストして指定することも可能です。以下はitemsのIDから「1」を指定して、そのitemに付与されているLikes（いいね）を指定するイメージです。

https://qiita.com/api/v2/items/1/likes

Method

次にメソッドです。Web API（REST）ではHTTPの原則に基づいて、GETやPOST・PUT・DELETEといったリソースに対する操作方法を指定します。

データを取得するのであればGET、データを追加するのであればPOSTといった指定になります。

f:id:sugimomoto:20191022145744p:plain

サポートしているメソッドはサービスによって変わるので、GETしかサポートしないリソースや、POSTだけを許容するリソースもあるでしょう。それぞれのAPIドキュメントでどんな操作方法を許容しているのか、都度確認する必要があります。

Query

Queryは主にデータを取得する際の各種諸条件を適用するために使われるパラメータセットのことを指します。

URLクエリ文字列、URIパラメータ、Query Stringなど様々な呼び方がされていますが RFC3986では単純にQueryと呼ばれていますので、QueryまたはQuery String（クエリ文字列）が正式な呼称でしょう。

URIとリソースを指定した後に続く文字列として「？」以降に指定するものがQueryです。Web API によって様々なQueryの指定方法がありますが、私が公開しているAPIでは「$select・$filter」といったパラメータをQueryでサポートしています。

f:id:sugimomoto:20191022145750p:plain

$select で取得したい項目 $filter でフィルタリング $orderby で並び替え $top で上位N件取得等ですね。

例えば2000円以下の本のタイトルと値段を取得して、値段安い順に並び替えて、TOP5を表示だと以下のようなQueryで取得することができます。

OReillyBookList?$select=Price,Title&$filter=Price le 2000&$orderby=Price&$top=5

何も指定しないと、不要なデータを取得してしまったりするので、Web APIを触る場合にはその Web APIがどんなQueryをサポートしているのか、慎重に識別しておく必要があります。

対象のAPIに対して、追加情報を渡すために使用されるプロパティセットを指します。主に後述する認証情報やどんなフォーマットでデータの受け渡しを行うのか？を指定することが一般的です。

例えば、昨今の Web APIはJSONフォーマットでやりとりをすることが一般的です。以下のようにContent-Type（Web APIに渡すデータの形式）がjsonフォーマットですよ、Accept（受け取るデータのフォーマット）がjsonですよ、といったような指定をします。

GET decodeapiserverdemo.azurewebsites.net/api.rsc/OReillyBookList
Accept: application/json
Content-Type: application/json
Authorization: Bearer XXXXXXXXXX

この指定するパラメータについても各APIで異なります。今回の Web APIでは以下のようにPOSTリクエストなどを見るとわかりやすいと思います。

f:id:sugimomoto:20191022145758p:plain

Body

Body は Web APIに渡すためのメインとなるデータを指定するための要素です。主にPOSTやPUTでリソースにデータを登録したり、更新したりする時に指定することが一般的です。

例えば今回のOReillyBookList APIでは以下のリクエストでリソースにデータを追加することが可能です。このJSONデータの部分がBodyの指定です。

POST http://decodeapiserverdemo.azurewebsites.net/api.rsc/OReillyBookList/ HTTP/1.1
Content-Type: application/json
x-cdata-authtoken: MY_AUTH_TOKEN

{
    "RowId": 1,
    "ImageUrl": "http://hogehoge/image.jpg",
    "ISBN": "43413241243",
    "Title": "New Book"
}

Web APIによってはXMLやCSVなど、様々なフォーマットを受け付ける場合があるので、これもAPI仕様書を確認しながら、登録するべきデータをフォーマットと一緒に作成します。

また、Web APIによっては、QueryやHeaderのような使い方をBodyで表現している場合もあるので、果たしてそのパラメータはどこに指定しなければいけないのか？　を慎重に見極める必要があります。

Authentication

最後に最も大事な部分である Authentication、Web APIを操作するための認証部分です。Web APIで認証を行うためには様々なアプローチがあるので、ここではあまり多くを語りません。

今回のOReillyBookList APIでは、ヘッダーに「x-cdata-authtoken」という指定でTokenを入力することで、認証が行われます。

POST http://decodeapiserverdemo.azurewebsites.net/api.rsc/OReillyBookList/ HTTP/1.1
Content-Type: application/json
x-cdata-authtoken: MY_AUTH_TOKEN

{
    "RowId": 1,
    "ImageUrl": "http://hogehoge/image.jpg",
    "ISBN": "43413241243",
    "Title": "New Book"
}

Web API によっては、UserID・PasswordによるBasic認証やOAuthといった認証・認可の仕組みでTokenを取得し、Headerに指定するなどのアプローチがあります。

QiitaではOAuthを利用したフローか、ユーザー管理画面から発行して、以下のようにHeaderに含めるというアプローチになっています。

https://qiita.com/api/v2/docs#%E8%AA%8D%E8%A8%BC%E8%AA%8D%E5%8F%AF

Authorization: Bearer 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd

ただ、一番理解しておきたいことは、一般的にこれらの情報を最終的に Header ないし Query でTokenなどの情報を指定する、という点にあると思います。（証明書によるプロセスなどの例外はありますが）

Postman を使って O'Reilly BookList の Web APIを叩いてみよう

Web APIを使うための要素を把握したところで、早速 Postman を使ってみましょう。

今回はシンプルにOReilly Book List APIを使って、データを10件取得してみたいと思います。

ドキュメントは以下の通りです。

http://decodeapiserverdemo.azurewebsites.net/api.rst#OReillyBookList

f:id:sugimomoto:20191022145813p:plain

Postman を立ち上げて、まずは対象となる Web APIのBase URIを指定しましょう。

OReillyBookListを提供しているサービスのBase URIは「http://decodeapiserverdemo.azurewebsites.net/api.rsc/」になります。これを Postman の以下の場所へ入力します。

f:id:sugimomoto:20191022145821p:plain

次にリソースを指定します。先程入力したBase URIの後ろに、OReillyBookListを入力します。

f:id:sugimomoto:20191022145826p:plain

次にMethodです。Postmanはプルダウンで各Methodを選択することができるようになっています。今回のAPIは仕様書を確認するとGET/POST/PUT/DELETEをサポートしていますが、データを取得するので「GET」をそのまま指定しておきます。

f:id:sugimomoto:20191022145831p:plain

次にQueryを入力します。PostmanにおけるQueryの指定はParamsタブで行います。

Paramsタブを選択し、データを10件だけ取得する指定をするので、Keyには「$top」Valueには「10」を指定します。このParamsタブにデータを入力すると、自動的にURIへQueryが補完されます。（逆もまた然りです）

f:id:sugimomoto:20191022145837p:plain

次に認証情報を追加してみましょう。Postmanは一般的な Web APIの認証方式を手軽に扱える機能がデフォルトで備わっています。今回のAPIはBasic認証が有効になっているので、Authorizationタブを選択し、認証のTypeから「Basic Auth」を選択、あとはUsernameとPasswordを入力すればOKという手軽なものになっています。

f:id:sugimomoto:20191022145842p:plain