暮らしの技術

暮らしを豊かにする技術や、特に暮らしを豊かにしない技術があります

Web API: The Good Parts 読んだ

Web API: The Good Parts

Web API: The Good Parts

読んだ

モチベーション

  • ここしばらく API を開発していたけれど，ずっと勘と経験を頼りにやっていてちょっと整理したかった
  • そのために補助線として本があると便利そうという感じ

読書メモ

1章
  • 第1章の最後に LSUDs (large set of unknown developers)` と `SSKDs (small set of known developers)` という概念に触れられていた
    • The Future of API Design: The Orchestration Layer で言及されている概念
    • その API がパブリックなものなのかプライベートなものなのかで設計の指針は変わりますね，みたいな感じ．
      • 重要で，ここを間違えると全然違うでしょって設計になってしまうと思う
        • あるウェブサービスがあった時，自社でアプリを作るので API 切りましょう，ってなった場合を考える
          • Twitter の API 真似してもうまくいかなさそう
  • 今回私は SSKDs を対象とした API の開発者/設計者という視点で読んでた．
2章: エンドポイント設計とリクエストの形式
  • 2.5 クエリパラメータの設計
    • 一覧を取得するような API で相対位置で取得するようなデザインは問題を生みやすいことが指摘されている
      • 経験的にも思うところがあり，絶対位置での指定の方がいいように思う
        • しかしそうなるとペーじゃの実装がむずい
          • ページャ，間違った発明だったのでは...
  • 2.9 HATEOAS と REST LEVEL 3 API
    • HATEOAS: 次に行える行動/取得するデータなどの URI をリンクとしてレスポンスに含める
    • REST LEVEL 3: Martin Fowler 氏が REST API の設計レベルっていうのを提案してる
      • その中では最終段階の LEVEL 3 に HATEOAS 概念の導入がある
        • 著者のコメントとして，SSKDs 向け API ではいいかもしれないけど LSUDs 向け API では合わないかもねみたいなことが書いてある
          • 私もそう感じます
3章: レスポンスデータの設計

エンベロープなしの例

{
  "friends": [100, 101, 102]
}

エンベロープありの例

{
  "results": {
    "friends": [100, 101, 102]
  }
}
  • 著者はエラーやメタ情報は HTTP のに寄せるべきという立場
    • ステータスコードなら HTTP のステータスを使えばいいしメタ情報は HTTP ヘッダに入れれば良い
    • 僕は違う考えがあって，現代のアプリケーションで発生するエラーは多様性にあふれており，HTTP のエラーコードでは表現力が足りないと思っている
      • 過去には HTTP Status は 500 にしつつカスタムヘッダとアプリケーションレスポンスにアプリケーションのエラーコードを含めるという実装をしました
        • ヘッダだと HTTP サーバのログフォーマットへ出力を追加しやすい
      • あと HTTP としては完全に成功していて，アプリケーション起因の問題のケースで 200 を返しつつボディのエラーを付与するという実装が入ったことがある
        • これはちょっと失敗だったかもしれない...
          • どうしても warning 的なレスポンスを表現したく，しかしエラーとして監視/カウントしたくないタイプのエラー（Expected but Unacceptedな奴．例えば会議室の予約システムで予約しようとした時間にすでに予定があるとか）ではあった
          • 4xx系のエラーステータス使えば? みたいな話はあるけど、「えっこれ別にエージェントが悪いわけじゃないですよね」みたいなモゴモゴした気持ちになる、上の例だと既に予定があるかどうか厳密には登録するまでわからないわけですし……
      • アプリケーション固有のエラーコードがあると，エージェントにより適切な情報を伝えられるので，その先にいるユーザやシステムが適切にハンドルできるようになる
        • と言っても全てのエラーにエラーコード降るのはコストがかかるのもあり，汎用エラーみたいなのは多用してしまったが...
    • 実際の例でいうとParse.comのレスポンスはエンベロープを採用していて、結構便利だったので採用したみたいなところがあります
4章: HTTPの使用を最大限利用する
  • キャッシュの話丁寧に説明されていて良かった
  • 独自のHTTPヘッダ定義するとき，最近は X- つけなくてもいいんじゃない? みたいな RFC が出てるらしく，へーって思った
    • RFC とはいえ "Best Current Practice" のやつだけど
      • 余談なんですが， X- は全部空いてると思いきや X-Content-Type-Options と X-Frame-Options が IANA で抑えられてるの知らなかった
5章: 設計変更をしやすい Web API を作る
  • むずいよねえ
  • オーケストレーション層を作って吸収する話は良かった，規模が大きくなってくるとそう言った動きも重要そう
  • 僕自身の経験を振り返ると以下の取り組みがあった
    • URI のパスレベルでバージョンを切る
      • /v1/users/:user_id/profile みたいな
      • レスポンスフォーマットのプロパティはだいたい追加は簡単，削除はむずい
      • リクエストフォーマットの必須項目追加は辛い
        • 必然的にオプションとして追加しつつデフォルト値を入れていくスタイルになりがち
6章
  • JSON ハイジャックの話が印象深かった
  • その他APIにおけるセキュリティのエッセンスが詰まってる感じで良かった
    • ヘッダ周りとかは割と抜けてることあるので確認しておきたい

エンベロープと HTTP Status との付き合い方はまだちょっと考えが足りないのと思うので折を見て考えたい

tanatana.info を作り直した

hugo でパコッとやったのでおなじみのテンプレートって感じ．トップページはちょっといじっている．

tanatana.info


そもそも今月末でこれまで使っていたさくらVPSのサーバを一台解約するので，それに合わせて引越しついでに作り直したみたいな感じ．

tanatana.info | Hugoでサイト作り直した

こんな感じになっていて，稀によくあるサーバと手元でコンテンツ違うんだけど，みたいなのが起きないようにしている.... 仕事だと割とこういう状態作るんですけど，個人だとなあなあにしがちなのよね．．．

deploy は専用ユーザを切って NOPASSWD で sudo 使えるようにするなどを行ったので，deploy ユーザの鍵が漏れると荒れる．本来ならユーザとかグループとかで適切な権限降って，NGINX のドキュメントルート周りだけ触れるようにしておくのが良いのだろうなと思うけどそこまでやれてない．

ついでに let's encrypt 入れたり mackerel エージェント入れたりした．

ブログと個人サイトの棲み分け

正直令和にもなって個人サイトも保持し続ける必要があるのか，みたいなのは気持ちがあるんですが，しかしまあスタティックなコンテンツをホスティングしたいことはある気がしていて，そう言う意味で何らかの場があるのは嬉しい気がする．

1ページだけなんだがCMSみたいな仕組みが欲しい……っ！となった時に使える夢のようなテク

暮らしを豊かにする

会社で仕事をしているとどうしても「この部分は非エンジニアが自由にいじれるようにしておきたいがそのための仕組みを作るときついね」みたいなことがあると思います。具体的には社内ツールの更新お知らせとかメモっぽいコーナーとか。

一方で更新する人には自由にして欲しくて、えーっと、じゃあ Markdown で Github.com 上から編集してもらってCIでデプロイするか……?? などとなりますが、この時点ですでに重いし人類のほとんどは Markdown に対応していません。

実は Google Docs の機能にWebに公開という機能があり、これを有効にしたドキュメントを iframe で埋め込むことにより、1ページだけWYSIWYGな編集画面を持つページを追加でき、しかもサーバ側の変更がほぼ不要、という夢のような機能を追加することができます。*1

  • ドキュメントの保存から反映に2〜3分時間がかかる
  • Google Apps のドライブで作ると設定によっては見えないことがあるっぽい

あたりが注意点という感じですが、普通に便利なのでおすすめです。スプレッドシートもプレゼンテーションも似たようなことができるっぽいぞ！

*1:[ファイル]→[ページ設定]から余白を小さくするとなお良いです

GAE/SE go111 + datastore emulator とりあえず動かす

これはメモです．

ディレクトリ配置

go1.11 以降かつ go modules を利用するので，これまでのように GOPATH に縛られない場所にプロジェクトディレクトリを作成できる．

様子

$ tree ./
./
├── datastore
│   ├── WEB-INF
│   │   ├── appengine-generated
│   │   │   └── local_db.bin
│   │   └── index.yaml
│   └── env.yaml
├── go.mod
├── go.sum
└── server
    ├── app.yaml
    └── main.go

go.mod の位置ここでいいの...? みたいな些細な疑問がありませんか? 私はあります．

Datastore Emulator

↑の tree の結果からもわかるように，プロジェクトルート/datastore をdatastore emulator用のスペースとして切っている．

$ gcloud beta emulators datastore start --project=YOUR_PROJECT_NAME --data-dir=./datastore

サーバの起動

環境変数の設定

起動まえに Datastore Emulator に向くよう環境変数を設定する．

$ cloud beta emulators datastore env-init --project=YOUR_PROJECT_NAME --data-dir=./datastore

アプリケーションサーバの起動

go run でもいいし， dev_appserver.py でもいいと思う． dev_appserver.py は余分なものが色々起動するけど自動でビルドが走るし再起動もしてくれるからありがたい．が，初期起動に時間かかりすぎるのでいい方法探したい．

dev_appserver.py ./server

新しいパートナーAPIがリリースされました

暮らしを豊かにしない

このクリスマスの日に side_tana の新しいパートナーAPIについてみなさんにアナウンスできることに大変興奮しています！

経緯





問題

パートナーの状態についてAPI経由で取得したいといった要求が急峻に高まっていることが知られています．また，これらのデータは一度デジタルデータにすることができれば，容易に配信可能であることが @tomohi_ro によって指摘されています．

そう，問題はいかに早く現実のステータスを反映するかにあります．

設計

本稿では SORACOM LTE-M Button と AWS IoT 1-Click, AWS Lambda function を用いることであらゆる状況においてステータス更新可能なシステムを実現しました．

f:id:side_tana:20181224003608p:plain

SORACOM LTE-M Button は名前の通り KDDI の LPWA を利用しており全国で使えるため，どういった場所でパートナーと結ばれても即時に状態を反映することが可能です．

デモ

ブツ

Public Read でございます．JavaScript SDKなら以下の感じで動く．

  const config = {
    databaseURL: "https://tana-partner.firebaseio.com",
  };
  firebase.initializeApp(config);
  const database = firebase.database();
  const rootRef = database.ref('/');
  rootRef.on('value', (snapshot) => {
    console.log(snapshot.val());
  });

更新方法

SORACOM LTE-M ボタンは通常のクリック以外に長押しもサポートされているので，今回は長押しを true，通常のクリックをfalse に割り当てました．ということで間違って押しても(あるいは振られても)状態を変えることが可能！便利！

犬さんは絶対にこれ使ってなんか作ってください．

終わりに

SORACOM LTE-M ボタンは標準で1500回の操作か1年間分の利用料が含まれています．つまりこれから1年が過ぎるか，僕が750人のパートナーに恵まれ，そして破局を迎えるその日までとりあえず利用できることになります．果たして出番は来るのか....?

まあとにかくこんな感じでガチャガチャ遊んでたら日付が変わってクリスマスになってしまったワケです．マジかー．メリークリスマス！

f:id:side_tana:20181224005537p:plain

QA

SLAを教えてください

ありません

本当に使われるんですか

知りません

ステータスと現実の状態に差異があった場合に補償はされますか

されません

サポート体制について教えてください

ありません

法人窓口はありますか

ありません

Legacy Partner API のEOLまでのスケジュールを教えてください

私はこれ以前にパートナーAPIをリリースしていませんので、どなたか別の方と勘違いされているのではないでしょうか?

パートナーリクエストAPIのロードマップを教えてください

申し訳ありません、現時点で公開できる情報はありません。