記事を書いてみました。仙台(2019)」でのLT用登壇資料ベースとして書いているので、後々スライドや登壇時の動画も公開するかなーと思っています。OpenAPI(Swagger)を取り込んでみようAPIリクエストはできた。APIを触ってみようと言う方向けに書いています。APIというものを聞いたことがあるけれど、イマイチ一歩踏み出せない。触り始めるためにどうしたらいいのかわからない。いうツールをきっかけにして踏み出してもらおうという趣旨です。みたいなところには突っ込みすぎません。APIのドキュメントは見たことあるけれど、ここからどうしたらいいのかわからない、という感じのところで読むと良いと思います。APIの開発者「提供する側・活用する側」双方にとってよりよい開発エクスペリエンスを提供するクライアントアプリケーションです。API開発者のためのコラボレーションプラットフォームとも呼ばれていますね。www.getpostman.com大まかな機能は大別して、下記の6種類提供されています。Client:公開されているもしくは開発中の各種APIを簡単にテストできる機能です。Testing:API開発者向けに各エンドポイントに対する自動テスト機能を提供します。Server機能を提供します。Documentation:PostmanのAPI定義から自動的にAPIドキュメントを生成し、外部ユーザーに提供することができる機能です。Monitors:提供されているAPIを定期的にチェックし、APIのアップデートや変更に伴う破損や従来のエクスペリエンスに変化が無いかモニタリングすることができます。Workspaces:チームでAPIを共同開発するためのコラボレーション機能を提供します。Client」に焦点を絞って紹介します。拡張機能として提供されていましたが、現在は各プラットフォーム(Windows版、macOS版、Linux版)のクライアントアプリとして提供されています。以下のURLからダウンロードして、インストールします。いう方は将来的に正式リリースが予定されている機能を試すことができるCanary版をダウンロードしましょう。APIを実行できるのか、事前に把握するべき重要な要素を確認します。APIはRESTという設計思想に(幾分か)則って公開されているものが多数を占めます。API提供者側でちょっとづつニュアンスが異なる部分もあるでしょうが、とりあえず「これさえ抑えておけば怖くない。APIを触るための7つの要素」があると思って大丈夫でしょう。APIをベースとして紹介します。APIを公開してみました。格安プランなので、あまりにアクセスがあると落ちちゃうかも。APIの作り方はこちらで書いています。APIを提供しているサービサーのURIエンドポイントを特定することです。APIでは以下のエンドポイントURIが対象になります。APIによっては、ここにバージョン名などが含まれる場合があります。場合は以下のように「v2」というバージョンが入ります。ここまでをベースとなるエンドポイントURIと今回は見なしていいでしょう。どんなデータを操作するのかを決める必要があります。Twitterであれば、ツイートやいいね、Qiitaであれば記事やチームなど。API(REST)では一般的です。APIでは以下のOReillyBookListがResourceにあたります。(実は設計思想的にはあまりよくない・・・。APIでいくと、以下の「items」がResourceです。このitemsに対してなんらかの操作をしますというのが、指定のイメージです。https://qiita.com/api/v2/itemsまた、エンドポイントによっては以下のように、リソースをネストして指定することも可能です。以下はitemsのIDから「1」を指定して、そのitemに付与されているLikes(いいね)を指定するイメージです。https://qiita.com/api/v2/items/1/likesMethod次にメソッドです。API(REST)ではHTTPの原則に基づいて、GETやPOST・PUT・DELETEといったリソースに対する操作方法を指定します。データを取得するのであればGET、データを追加するのであればPOSTといった指定になります。サポートしているメソッドはサービスによって変わるので、GETしかサポートしないリソースや、POSTだけを許容するリソースもあるでしょう。それぞれのAPIドキュメントでどんな操作方法を許容しているのか、都度確認する必要があります。QueryQueryは主にデータを取得する際の各種諸条件を適用するために使われるパラメータセットのことを指します。String(クエリ文字列)が正式な呼称でしょう。URIとリソースを指定した後に続く文字列として「?」以降に指定するものがQueryです。よって様々なQueryの指定方法がありますが、私が公開しているAPIでは「$select・$filter」といったパラメータをQueryでサポートしています。上位N件取得等ですね。2000円以下の本のタイトルと値段を取得して、値段安い順に並び替えて、TOP5を表示だと以下のようなQueryで取得することができます。APIがどんなQueryをサポートしているのか、慎重に識別しておく必要があります。Header対象のAPIに対して、追加情報を渡すために使用されるプロパティセットを指します。後述する認証情報やどんなフォーマットでデータの受け渡しを行うのか?を指定することが一般的です。APIはJSONフォーマットでやりとりをすることが一般的です。APIに渡すデータの形式)がjsonフォーマットですよ、Accept(受け取るデータのフォーマット)がjsonですよ、といったような指定をします。XXXXXXXXXXこの指定するパラメータについても各APIで異なります。APIでは以下のようにPOSTリクエストなどを見るとわかりやすいと思います。APIに渡すためのメインとなるデータを指定するための要素です。POSTやPUTでリソースにデータを登録したり、更新したりする時に指定することが一般的です。APIでは以下のリクエストでリソースにデータを追加することが可能です。このJSONデータの部分がBodyの指定です。APIによってはXMLやCSVなど、様々なフォーマットを受け付ける場合があるので、これもAPI仕様書を確認しながら、登録するべきデータをフォーマットと一緒に作成します。慎重に見極める必要があります。APIを操作するための認証部分です。APIで認証を行うためには様々なアプローチがあるので、ここではあまり多くを語りません。APIでは、ヘッダーに「x-cdata-authtoken」という指定でTokenを入力することで、認証が行われます。よっては、UserID・PasswordによるBasic認証やOAuthといった認証・認可の仕組みでTokenを取得し、Headerに指定するなどのアプローチがあります。QiitaではOAuthを利用したフローか、ユーザー管理画面から発行して、以下のようにHeaderに含めるというアプローチになっています。Tokenなどの情報を指定する、という点にあると思います。APIを使って、データを10件取得してみたいと思います。ドキュメントは以下の通りです。URIを指定しましょう。URIは「http://decodeapiserverdemo.azurewebsites.net/api.rsc/」になります。以下の場所へ入力します。次にリソースを指定します。URIの後ろに、OReillyBookListを入力します。次にMethodです。Postmanはプルダウンで各Methodを選択することができるようになっています。今回のAPIは仕様書を確認するとGET/POST/PUT/DELETEをサポートしていますが、データを取得するので「GET」をそのまま指定しておきます。次にQueryを入力します。PostmanにおけるQueryの指定はParamsタブで行います。Paramsタブを選択し、データを10件だけ取得する指定をするので、Keyには「$top」Valueには「10」を指定します。このParamsタブにデータを入力すると、自動的にURIへQueryが補完されます。(逆もまた然りです)次に認証情報を追加してみましょう。APIの認証方式を手軽に扱える機能がデフォルトで備わっています。Auth」を選択、あとはUsernameとPasswordを入力すればOKという手軽なものになっています。最後にHeadersを指定します。API、実は様々なフォーマット(JSONやCSV、TSVなどをサポート)でデータが取得できるのですが、ここでは明示的にJSONフォーマットでデータを取得したいと思います。Headersタブを選択し、データ取得のフォーマットを指定するための「Accept」をKeyに指定します。ValueにはJSONを指定するため「application/json」と入力します。これで準備は完了です。APIを実際にリクエストするにはPostman右上にある「Send」ボタンをクリックします。APIへのリクエストが成功すると、画面下の部分にデータを取得した結果が表示されます。いうのは巷にあふれているものです。アクセスしてみましょう。APIを展開しているサービスのテンプレートが自由にダウンロードできます。Postman」をクリックすれば以下のように、Twitterのリクエストテンプレートが自動的に追加されて、ここからAPIを試していくことができるようになっています。どちらかと言えばグローバル向けなので、国内のクラウドサービスAPIはほとんどありません。APIが「OpenAPI(Swagger)」と呼ばれるAPI定義の情報(Spec)を公開していれば、それを取り込んでリクエストテンプレートにしてしまうことも可能です。Specを公開しています。https://developer.freee.co.jp/OpenAPI(Swagger)Specは以下のReferenceから入手できます。そのままダウンロードすればOKです。https://developer.freee.co.jp/docs/accounting/referenceこんな感じのJSONデータになっています。PostmanのImport機能から取り込めます。画面右上の「Import」をクリックしてください。File」タブから、ダウンロードしたOpenAPI(Swagger)Specを指定します。API情報が取り込まれました。ここから簡単にAPIリクエストを実行できます。APIリクエストはできた。APIを操作することがほとんどだと思います。リクエストを選択した状態で「Code」の文字をクリックします。すると以下のようなダイアログが表示されて、右上のプルダウンリストから各種プログラミング言語を選択できるようになります。これで対象となる言語を選択すれば、そのままリクエストが実行可能なCodeが生成されるというわけです!便利ですねー。このあたりの機能も活用してみてほしいと思います。Centerにアクセスしてみてください。使いこなせるようになると思います。みたいな時にはとても役立つと思います。情報まとめ様々なクラウドサービスのAPIについて触れて回るまとめ記事。(翻訳)Twitter@sugimomotoさんのツイートはてなブログをはじめよう!sugimomotoさんは、はてなブログを使っています。ブログを報告するスターをつけました引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。