かつて技術でイキっていたこともあった老兵たちのための REST API 入門
Old soldiers never die ♪
Never die ♪
Never die ♪
Old soldiers never die ♪
They just fade away ♫
・・・やかましいわ！！
このブログ記事の想定読者は、
「え、API？ SOAP/WSDL のこと？」
・・・という時代に取り残された
経験豊富な老兵熟練エンジニアです。
完全に理解している REST API を
念のため、サラッと振り返るため
の記事です。
そう、すべては念のためなのです。
（あと、今回は Blue Prism、関係ありません☆）
REST API って何？
・・・え、マジ？
そこから？
そこからいっちゃう？？
REST API って何？
・・・っていう記事は、
世の中にはたくさんあるし、
だいたい、言っていることは
近しいことなので、そこを
見ればだいたいのことは
わかるはずです。
RPA みたいに原典をあたりも
しない手前勝手な定義が氾濫
しているわけでもないしな！
ここで、ロートル熟練エンジニア
にとってポイントなのは、
以下の２点だと思います。
- 入出力データ形式
- HTTP メソッド
入出力データ形式
SOAP/WSDL だと XML が大前提で、
それぞれ名前空間を切って、
独自の XML スキーマを定義していた
と思います。
しかし、REST API の場合、
データ形式には特に縛りはありません。
そう、別に入出力のデータ形式が
JSON だから REST API と
言っているわけではない
ということ、これはポイントです。
出力データ形式が XML でも
REST API の定義にはかなうし、
入力データ形式は base64
エンコーディングされた文字列
かもしれません。
しかし、実際は JSON が多い
好きになれないんだよなぁ、これ。。
いや、自由で良いことだとは
思います。
ただ、XML のように厳密な定義は、
あまりされていないように思います。
JSON にも JSON スキーマというもの
があるのですが、ほとんど見かけない。。
圧倒的多数は、XML 黎明期の
フリーダムな XML に近い JSON
ばかりです。
SOAP/WSDL で慣れた熟練エンジニアは、
JSON を見てチャラいな～と思うかもしれません。
しかし、そこで眉をひそめることなく、
「お、最近はこういうのが流行っているのか～。」
「おじさんの若い頃も、DTD っていうのがあってな～。」
・・・という塩梅で、
老害マウンティングしていく
ことがお薦めです。
時の流れという絶対的なパワーに
抗うには、手段を選んでは
いられないのです。
JSON 形式のデータのパース
JSON 形式の文字列から
特定の項目を取り出す方法もあり、
JSON Path などが代表例です。
はい、XPath みたいなもんですね。
「なにこれ、もう XML でいいじゃん」
とか言ってはいけません。
否定から入ってはいけないのです。
なぜなら、老兵として切り捨てられる
だけだからです。
肯定から入って、老害マウンティング。
これが正しい振る舞いです。
HTTP メソッド
REST API の仕様でもうひとつのポイントは、
この HTTP メソッドです。
かつて悠久の時代、
熟練エンジニアが HTTP メソッドについて
新人研修で習ったときは
- HTTP メソッドで実際に使うのは POST と GET。他は忘れて良し（テストにも出ない）
- しかし GET は URL パラメータが表示されてしまうので、画面を横からチラ見された際に情報漏洩のリスクがある。したがって GET も忘れて良し
- 結論：HTTP メソッド＝POST
といった形であったと思います。
SOAP/WSDL の世界では、
HTTP メソッドは POST に固定され、
API の操作は operation として
処理単位に WSDL 上に定義されて
いたと思います。
しかし、REST API では操作したい
リソース単位に URL が用意され、
リソースに対して GET したり、
POST したりする形になります。
パラメータ設定のお作法も変わる
HTTP メソッドを使うので、
GET 時は URL パラメータを利用し、
POST 時は HTTP リクエストの中身に
（多くの場合）JSON テキストを
入れる形になります。
SOAP/WSDL のときのように、
いずれも HTTP リクエストに XML
で書いて、POST で送る形では
ありません。
ここをちゃんと抑えていないと、
コンテンツ本体をこの verb-type では送信できません。
というエラーが出る原因になります。
逆に言えば、ここを抑えておけば、
「オレはただのロートルじゃない」
というアピールも、
ぐっと現実性を帯びます。
ここが頑張りどころです。
REST API の認証（認可）
SOAP/WSDL で認証と言えば、
SAML がどうとか、ケルベロスがどうとか、
Basic 認証とかダッセーよなぁ、
・・・とか、そういう話だったと思うが、
例によって認証（認可）でも、
熟練エンジニアは新しいことを
覚えなくてはならない。。
そう、API トークンです。
API トークン
REST API での認証は、API トークン方式が多い。
仕組み自体は特に複雑なものではなく、
事前に Web サイトなどで認証したうえで、
API トークンを発行し、
REST API 利用時に HTTP リクエストのヘッダ
に入れるだけです。
REST API はリソースへのアクセスなので、
認証と認可（Authorization）がセットになって
いるようなトークンですね。
Bearerトークン
HTTP ヘッダへの入れ方も、
いろいろとお作法があるが、
Bearer トークンは主なものの
一つだと思います。
これは、HTTP ヘッダに
Authorization: Bearer 「ここにトークンそのものを入れる」
と記載する方式です。
類似した方式は他にもあり、
Authorization: xxx 「ここにトークンそのものを入れる」
などのパターンがあります。
（xxx には固有の文字列が入る）
なんだよ、標準化して統一しとけよ
きちんと API ドキュメントを確認しましょう。
Bearer って何？
ちなみになんで"Bearer"という
聞きなれない単語を使うのか。
たぶん間違っていると思いますけど、
無記名債権のことを Bearer Bond という
ので、そのイメージが近いな、と感じました。
無記名債権は商品券とか、映画のチケット
とかで、要は名前も書いてないし、
所有者のハンコもおしてないものですけど、
Bearer トークンもまた、
名前が書いてないですからね。
だから間違って誰かの手に渡ってしまうと、
そのまま使われちゃいますね。
まとめ
- 若者にまざるための REST API 入門
- これが良いものかどうか、そういうことを問題にしてるんじゃなくて、どうやれば若者に混ざれるか、それが問題だ（断言）
まぁ実際、かなり自由な仕様だと
感じますけどね。データ形式と言い、
認証（認可）と言い、API ドキュメント
の書き方といい・・・
もっとも、技術の世界って、
こういう一面があるので、
キャッチアップはせざるを得ない。。
他にもそういう側面が、
あるんじゃないかなぁ。
たとえば、Java とか。
荒れそうだから書かないけど
