皆さま、API仕様書ってどうしてますか？
会社によっては社内のナレッジベースみたいなところにあったり、Excelとかになってたりすると思います。
弊社ではこの度、メンテナンスが簡単で外部にも公開できるようなAPI仕様書作成ツールを探しており、今Postmanというのを検討しています。
Postmanは、メインの役割としてはWebサーバーにあるプログラムに何か値を「GET」とか「POST」で渡すときに、それが簡単にできるというプログラムです。
Postmanとはもう長い付き合いで、確か12年前ぐらいからあったんじゃないかな~
Perlで問い合わせフォームとか作ってた頃から、これを使ってテストしてた気がする。昔は、本当に何かをURLにPostするだけでしたが、今はめちゃ高機能になっているみたいです。
というわけで、ちょいちょいPostmanをAPI仕様書にしていく中で得られた便利な使い方を紹介していきたいなと思います。
まずは、「成功したとき」と「失敗したとき」でドキュメントを分けたいやつです。ほかのプログラマーさんにこういうニーズがあるかわかりませんが、とりあえず私は 「成功したとき」と「失敗したとき」 が知りたいです。
成功したときにどんな風に帰ってくるのかは普通でも必要だと思いますが、失敗したときにどのようにエラーが帰ってくるのか知りたいからです。
で、Postmanさんではその辺をカバーしてくれとります！ありがとう！♡
以下、やり方です。
① 普通にAPIにリクエストを送ります。Postmanを初めて使う人のために紹介しますと、POSTとあるところにURLを記載し、Params とあるところにGETパラメーターを入力、BodyとあるところにPostパラメーターを入力して、Sendと書かれた青いボタンをクリックします
②レスポンスが帰ってきたら、下記の赤丸をクリックしてください。すると、「Save ad example」というのが選べます。この度はリクエストに成功しているので、「リクエスト成功時」などという名前をつけます。
③すると、左のツリー構造でAPIを見れる場所で、このリクエストが成功したときとエラーの時のサンプルがあるんだなぁ~ とわかります。
便利ですね！
