この本はフランス人システムアーキテクトのアルノー・ロレの『The Design of Web APIs』の邦訳です。
Web API、もっと言えば REST について、基本的なことからセキュリティやネットワーク、ドキュメントに関わることまで、知っておくべきことを広く丁寧に説明している本でした。
RESTの基本に関してはこの本でなくても勉強できると思うので(自分の場合はオライリーの『RESTful Webサービス』 でした)、その知識がある人は改めて読まなくてもいいように思います。
ただ、その上で設計について「こういう時はどうすればいいんだろう」みたいなよくある疑問について、選択肢を挙げた上で「私はこのやり方をおすすめします」的な 著者の意見が書かれている ので、そこに関しては1つの参考になると思います。
あとは APIのドキュメントをどう書くか 、については自分はあまり本でこの辺りを勉強していないので、いざ書こうとなったら役立つだろうと思います。Open API Specification で書く場合の具体例がたくさん出てきます。
3部構成になっていて、第1部はAPIの基礎、第2部は設計で、この2つのパートは基本的に「理想」が書かれているように思います。
第3部からはもう少し現実的な話が出てきます。ページングやキャッシュ、バージョニングあたりの話が出てきます。
必要な章だけ独立して読めるか、でいうと、紹介されている例が基本的に続きものなので、順番に読んだ方が分かりやすいと思います。
他の開発者にとって分かりやすい設計をするべき という考えで一貫した意見を書かれていると思います。
本の中で架空の家電のUI(インターフェース)を何度も例えとして出して、「家電のUIが分かりづらかったら使いづらいですよね？表記や配置、表示単位がばらばらだったら困りますよね？APIも同じですよ」というような話をしていて、分かりやすい例えだなと思いました。
使う側の立場で設計するということは、提供する側、つまり 開発する側の都合を設計に反映させてはいけない ということです。
データベースにこう格納されているからそれをそのまま返す、みたいなことはやめましょうという話です。この辺は個人的にはかなりやりがちではと思います。
ついでにいうと同じリソースの情報を返すAPIでも、各APIのコンテキストに必要なプロパティだけ返しましょう ということも書かれています。現実には複数のコンテキストに対応できる、プロパティがいっぱい生えたオブジェクトを返しがちだと思うので、これを守るのはちょっと手間がかかりそうです。
APIがやりとりする内容は機械が読み書きするために存在していますが、それでも開発するのは人間なので 内容を人間が読める方がベター、というスタンスです。
例えば日付を返す時にUNIXタイムスタンプとして返すというやり方がありますが、それでは人間には分からないので "2021-03-22" のように人間が読めるようにしましょうという内容です(あるいはヒューマン・リーダブルなプロパティを別に用意する)。
他にenumをnumberで返しているところも、理解できる文字列で返した方が開発者にとってはいいという話です。
設計に使うツールとして「ゴールキャンバス」という表が2章以降よく出てきます。
1つ1つのAPIを、ユーザーが何かを達成するための「ゴール(目標)」ととらえて、それぞれのゴールを洗い出しながら設計するやり方を説明しています。表の列は以下の6つです:
この表を埋めていくことで全体を把握して、足りないところや統一性のないところ、そして無駄なものに気付ける、というのがメリットだと思います。
音楽プレーヤーの「再生」「一時停止」のシンボル(マーク)はISO 7000で定義されているそうで、このアイコンを知っているユーザはこれが使われているどの製品でもその使い方を推測できる、という話が6章に出てきます。
これと同じで、APIの開発者は 既に誰かが定義したものを使うことでAPIの使い方を推測しやすくできます 。また車輪の再発明を防ぐことにもなります。
以下は紹介されている規格(他)です:
application/vnd.bank.2+json。vndはvendor)application/vnd.bankingapi.extended+json)基本的にAPIのバージョニングをしたとしても、後から設計を変更するのは大変なのでどんな構造だと拡張しやすいか、ということを知っておくといいという話です。
例えばリストをそのままJSONで返すのではなく、items のようなプロパティにリストを入れたオブジェクトを返すようにします。後からページネーションのようなメタデータを追加できるためです。
基本的にはオブジェクト > 文字列 > bool や数値の順で拡張しやすくなります。
例えば { "active": false } より { "status": "INACTIVE" } の方が後から変更しやすい(この場合はEnumの要素が増やせる)、ということかと思います。
「更新日」「作成日」のように日付を表す情報を「イベント」として表してリストの形でもっておけば、何らかの日付を追加する時に専用のプロパティを追加をする必要がない、みたいな話も載っています。
まあこれに関しては実際にうまくいくかはものによると思います。
/transfers/delayed/{transferId} ではなく /delayed-transfers/{transferId} にすればいい(リソースIDの前は複数形、という統一感が失われない)me というパラメータを用意することもできる (マジックリソースIDと読んでいる)POST /some-resources)で複数のパラメータをリストで渡せるようにするか、POST /some-resources/batch のような専用のAPIを生やす必要があるここまでで書いていないことで他にも参考にできそうなことは色々ありました。セキュリティに関して、スコープの切り方とかも説明されているのですが、実践したことがないので載せていません。
最後の13章に、設計したAPIを検証するためのチェックリストが載っていて、この辺を本当にちゃんとチェックできていれば実際使いやすいAPIになる気がします。
あとは単純にAPIのリファレンス以外にも、ユースケースを説明するドキュメントや設計ガイドラインも用意しましょうという話がありました。
この本全体を通して言えるんですが、これってWeb APIに限らず通常の開発でもやった方がいいことばかりなんだよな…と思います。APIに統一感をもたせる、推測しやすくする、必要なものだけ渡す、などもそうです。
最近出ている勉強会で「誰にでも分かる設計というのはフィクション。いい設計を目指した上で情報共有(教育など)も必要」的なことを言われている方がいましたが、まさにその通りだなと思いました。
どんなに個々のパッケージやクラスがいい設計と言えるとしても、全体像が見えるかと言われれば他に説明は必要で、APIがAPIリファレンスを見ただけではすぐには使いこなせないのと同じことかな、と思います。
まあ何が言いたいかっていうと「いい設計にしようと頑張るのも大事だけど、ドキュメントを書くなど説明する努力も大事だな…」ということでした。
そういえば『ハンズオンNode.js』で「Server-Sent Event」というもの(サーバーからのみ非同期でクライアントにデータを送れる)が出てきて、そんなんあったんだ…と思いましたが、ちょっと前に聴いた mozaic.fm のどこかの回で「まだあったんですね」「使ってる人いるんですか」みたいな話になっていた気がします。結局これ活用してる人いるんですかね :thinking:
]]>コロナウイルスの流行による緊急事態宣言で、自分の会社でも在宅勤務が始まりしばらく経つのですが、特に在宅勤務が始まった当初は 快適に仕事したい ということで色々と必要なものを購入しました (主にケーブル類)。
その買った中で 一番高いもの が AOC というメーカーのゲーミングモニタでして、その感想を書いておこうと思います。ちなみにゲーミングモニタを買ったのは初めてで、アマゾンで 3万8千円弱 で購入しました。ちなみにさっきアマゾンで同じ商品を見たら9千円くらい値上がりしている気がしますが、理由はよく分かりません。
「快適に仕事したい」をちゃんと読んだ人は「ゲーミングモニタ」にツッコミを入れたいかもしれませんが、大事なことを先に書きます。
1920 * 1080 はフルHDとも言われます。まわりの人で 4K (3840 * 2160) モニタを買っている/持っている人がいる中、まさかのしょぼい解像度です。というか元々23型で同じ解像度のモニタは持ってました。あと会社から貸与されている 15 インチの MacBookPro は Retina でも 1920 * 1200 で縦幅は負けています。
自分はこの辺に詳しくなかったのですが、買うときに調べて分かったのは TN は 正面以外から見ると色が綺麗に見えない ということです。どうやら昔の MacBook Air はこれだったみたいです。対して 最新の Air や Pro はIPS 液晶というやつで、これは斜めからモニタを見てもちゃんとした色で見えます。
ちなみに自分が昔から持っていた三菱の23型もIPS液晶です。解像度が同じで色の表示も微妙なTNを買ったらただのダウングレードでは? と思われるかもしれません…
すみません、前振りが長かったのですが、欲しかったのはこれです。リフレッシュレートというのは、1秒間に何回画面を書き換えるのか、という数値です。既に持っている三菱の昔のモニタは最高でも 60Hz 、つまり1秒間に 60 回書き換え可能で、それと比較すると 今回買ったモニタは4倍速く書き換えられる ということになります。
書き換える速度が最大で4倍ということは、それだけ 滑らかに見える 、ということで、だからこそゲーム向きのモニタということになります。
一方 4K モニタは解像度が高い分、リフレッシュレートは 60 Hz というものが多いと思われます。つまり自分が買ったモニタは 4K と比べて、画面サイズを4分の1にする代わりに4倍の書き換え速度をとったモニタということです。
データ上のスペックはともかく実際に使ってどうか? という件についてですが、「確かに滑らかだけど、自分のマシンの性能的にコンスタントに 240 fps は出ないので 144Hz でも十分だった」というのが正直なところです :sob:
ゲームのリフレッシュレートの話は自分が聞いている Rebuild.fm でも割と最近話題に上がっていたのですが、正直難しいところで、そもそもゲームによって出る fps は変わりますし、各ゲームの設定によっても変わります。解像度を下げたりゲームのグラフィックスをショボくすればその分 fps を稼ぐことはできなくもないです。ただ結局ある程度、綺麗な映像ではやりたいので例えば自分のやっている Borderlands 3 という FPS だと、グラフィックをウルトラ(上から2つ目の綺麗さ)の設定から一部ショボくした感じで落ち着き、それだとせいぜい 100 fps しか出ませんでした。
という訳で、今までゲーミングノートPCの画面 (ちなみに144Hz) よりも物理的に広い画面である程度滑らかな映像でゲームができる、というのは良かったです。慣れてくると何も思わなくなってきましたが、最初は敵の撃ってくる弾やらが避けやすいかも、と思いました。ただ 240Hz はいらないよね、というのが結論です。:sweat_smile:
まあ上で書いたようにオーバースペックでしたが、色々よいこともあります。細かい点では
結局、仕事と全く関係ない外部モニタを買った訳ですが、これには個人的な理由があります。最初は仕事用に大きいモニタを買うことを考えて探し始めたのですが、よく考えたらそれを置ける奥行きがあるデスクを持っていないことに気がつきました。
ならば小さいけど性能がいいものを、と考え始めたらゲーミングモニタに行き着いてしまった、というのが真相です。また在宅勤務はいつかは終わるだろうと思ったので、それもあって仕事よりも趣味用にしました。
もちろんゲーミングということならワイドな湾曲しているやつ、とかもいつかは欲しいと思いますが、今回買った 24.5 型というサイズは eスポーツの大会でも使われるモニタのサイズらしく、なんだかんだでバランスがいい気がします。会社では 40 型くらいのモニタを使っているのですが、画面が広すぎて全体を把握できません。ゲームによっては むしろ全体を把握したい はずなのでそこまで広い必要はなくて(世界観を楽しむジャンルのゲームをのぞく)、液晶パネルが TN なのも そもそもゲーム用なんだから正面からしか見ない 、ということを考えると合理的な割り切りだと思います。
ついでに今回初めてゲーミングモニタを買ってみて、液晶パネルの方式やHDMI/DisplayPortのバージョン、自分のPCのGPUまわりの設計 (NVIDIA の Optimus) や FreeSync と G-SYNC の互換性など色々調べる羽目になり、結果的にちょっと勉強になって良かったと思います。おしまい :triumph:
とりあえずメモだけでも。自分は普段 Mac 使いで Win/Linux のデュアルブートは初めてなので色々間違ってるかもしれません。
Dell の Alienware m15 というゲーミングノートPCを買った。数ヶ月で別バージョンが出るけど自分が買ったのはGeForceのRTX 2070 Max-Qが載りCore i7が6コアの世代。 待ってればCPU 8コアでRTX 2080が載るやつが出ると思う。 あと毎週何らかの値引きをしているので焦る必要なし。メモリのアップグレードが無料になったり、ストレージやグラボのアップグレードが安くなったり、5%オフになったりと毎週ネタが変わるので自分のニーズに合わせればよし。 ついでにいうと受注(当然カスタム)から15日後に届きました。
今後の話に関わる部分として、 SSD 2台内蔵 (512GB * 2) オプションにした。デフォルトでは SSHD という SSD と HDD のハイブリッドのやつがついてくるけど、ドライブ毎にOSを変えたかった(これ自体の理由は何となくその方が綺麗そうだし、同じドライブでやるとWindowsアップデート時に何かややこしいことになったりする気がした)ため。その分かなり高くなるけど我慢。あとHDD重いし。
会社の同僚に教えてもらった Pop!_OS にした。Ubuntuのデュアルブート情報を調べてると NVIDIA のグラボ周りでやや作業が必要そうで、その点 Pop は最初から NVIDIA のグラボへの対応が良さそうだった。あと見た目がシンプルかつほのぼのしている。
あとTensorflow(GPU利用)とかそのあたりを入れるのも楽そう。
東芝製の8GBのUSBメモリーカードを数個。 balenaEtcher というツールでLinuxのインストールメディアを作った。 Windowsの回復用にも使おうと思ったが16GB必要だったので結局コンビニに買いにいった。
あと有線の安いマウス(Linux対応と書いてあるゲーミングマウス)を買っておいた。トラックパッドがうまく動かなかった時用。あとついでにゲームにも使えて一石二鳥。
Etcherで作成後にマウントできないって怒られるので作るのに失敗したかと思って焦った。ちゃんと作れたか確認したいなら普通にそのメディアから起動してみるのが早い。
既知の問題。Dell のサイトに解決方法が書いてある。失敗するとこれだけで再度3、40分くらい時間をとられるので注意。
ネットで情報を見ていると BIOS の Fast boot をオフにする話が出てきたけど、自分のマシンの BIOS にそういう設定は見当たらなかった。
それとは別に Windows 10 の OS の機能としての高速起動はオフにしておく。
正確には起動しても「問題があって起動できないから再起動するでー」となる。Safe BootをDisableするのと同時にやったらそうなった。下記サイトの通りにやり、Safe bootはこの手順と別にDisableすれば安全。
https://github.com/awesomebytes/alienware15r3_ubuntu14#get-windows-to-boot-on-ahci-mode-sata-options
これは Pop!_OS 特有なのかもしれないけど Legacy な Boot をオフにすると Pop!_OS の画面が Try の選択後何も表示されないままになった。Ubuntu のインストールではEを押して「nomodeset」を追記しろみたいなのが多くてそれが原因かと思ってたのでしばらくはまってた。この辺の理由は正直詳しくないのでよく分かってない。
800 * 600 で表示されてダイアログの下にあるはずのボタンが押せず非常につらい。結局タブやスペースを駆使してキーボードで操作して何とかした。特にインストールするドライブを選択する時はWindowsの入っている方を選択しないよう要注意。左上のActivityをクリックするとウインドウの全体が見えるのでそれを頼りにやる。ここはもっといい方法があるはず。
Mac や Win とかだとディレクトリ名を日本語表示した時に「ダウンロード」と表示される一方で実際のディレクトリ名は「Downloads」みたいな仕組みがあると思うけど、Linuxはそうじゃないらしく、あとで cd とかする時に日本語を打つのは気持ちが悪いので英語にしておいた方がよさげ。
よく分かってなくて GRUB の設定をめっちゃ変更してたけどそうじゃなくて bootctl の設定を変更する。mount でWindowsのEFIパーティションをマウントしてMicrosoft以下のファイルをLinuxドライブの /boot/efi にコピペして、さらにtimeoutの設定をファイルに追加すると電源入れた時にLinuxとWindowsが時間制限付きで選択できるようになる。めでたしめでたし
Windows 側で最初OSのライセンス認証が未認証の状態になってるけどトラブルシュート押せば直る。
Linux から Win に切り替えた直後は時刻がおかしい。
Linuxとのデュアルブートがうまくいかなかった時用に Windows 10 Pro オプションを選択したけど(Docker使うつもりだった)結果的にはいらなかった。
トラックパッドも特に問題なかったけど、何だかんだでMacのトラックパッドに敵わないので有線マウスは買っておいて損なし。
モニタを144HzのFHDにするか60HzのUHDにするか迷ったけど、とりあえず開発/ゲームともに前者でも問題はなかった(自分的には画面がそこまで微妙とは思わない)。144Hzの恩恵は正直60Hzと比較してないから分からない。多分…滑らかなはず
Pop!_OS すばらしい。OS公式の tensorflow-cuda みたいなパッケージがあってその辺をやりたい場合もインストールは楽。さっきtensorflowのサンプルちょっと実行したけどちゃんとグラボは認識してる(逆にいうと省エネしたい時にCPU内蔵のGPUに切り替えられるかは確認してない…)。あと基本はUbuntuなのでその辺の情報が割と参考になる。
Win 側で Borderlands 2 やって全グラフィックオプションをつよつよにしたけど本体の画面(フルHD)ではプレイ中ほとんど144FPSキープしてた。
FF15のベンチマークはフルHD高品質で「快適(スコア 7000台、GTX 1070 Tiの結果と同じくらい)」だった。ただたまーにカクつく。最初から最後まで完全に途切れない、ということはなかった。Steamにある体験版やったけどこちらはスムーズそのものだった。ニコ動にあるPS4版の実況動画(ナポリの蘭たん)をそのあとで見たけどまあ動画自体の画質もあるとはいえ自分のマシンの表示よりは微妙な感じがした。
Linux側でキーボードを光らせる方法を探したけど、このマシンに対応したツールはまだないっぽい。USBまわりが詳しくないとこの辺は無理そう。
普段 MacBookPro 13インチ(2015年の) を入れているA4くらいまで対応のビジネスバッグには入らない。横幅はいけるけど奥行?がはみ出る。
今までやりたかったけどできなかったゲームをSteamのウィッシュリストに30本ほど追加したけど、ラストオブアスとデトロイトビカムヒューマンてまだPC版はないのね…まあ他にもいくらでもできるゲームあるからいいんだけど。
正直、最後までDellかASUSで迷ってたがこれはまだ出てなかった。Alienwareよりベゼルは最低限だし、サイズも小さく、100gほど軽い。RTX 2080が載る。電源アダプタも多分小さいのが使えそう。もっと早く出しなさいよと(笑)。とはいえ値段とか考えると載るからといって選ぶとも限らないので今のところ後悔はなし。
https://www.asus.com/jp/Laptops/ROG-Zephyrus-S-GX531/
以上
]]>エンジニア組織論への招待に続きマネジメントに関わる本。
後半は複数チームの管理や管理者の管理の話など、自分の今の立場とは遠い立場についての話で逆におもしろい。
2章くらいのメンタリングの話は組織論の方が具体的でおもしろかったかも。
自分が読んで感じたのは、管理者っていうのはどのレベルの人であっても、自分の管理する部下やチームを色んな意味で「成功させる」ために頑張る仕事なんだな、ということ。部下のスキルアップ、昇進やプロジェクトの成功のために頑張って、それが自分自身の成功になるってこと。その辺「マネジメント」っていう単語だけだと伝わりにくいなと思う。
こまかいところで印象に残ったところでは、1on1はやって当たり前、あとリリース頻度を高くするのは当たり前みたいなとこ。特に後者は自分がずっとそのために色々手をつけていることもあって印象に残った。1on1は最近やってないな。
あとはタスクの分割について。メモっとこ:
アジャイル開発を導入したにもかかわらず、作業の細分化の価値を理解できていないチームを主導するのは容易なことではありません。
(略) チーム状況を知るのに有効な尺度が「製品アップデートのリリース頻度」です。もしもあなたの会社が頻繁にリリースすることの意義をわかってくれないとすれば実に残念な話です
ちなみにこの本では週1でも少ないぐらいの空気
(略) 上司に求めるべきことの第1ですが、それは「1対1で行うミーティング(以下「1-1」)」です。これは直属の上司と仕事上、良好な関係を保っていく上で不可欠な要件です。
あとは最後の章がいいな。そこまで読んであー管理者って本当大変だな…て思っているところに、大事なのはいつでも「好奇心をもちつづける」みたいな話になって、それだったらできるかも、って思ってあたたかい気持ちで読み終えられる。他の人と意見が対立する時も、どうしてこの人はこう考えるんだろう? と興味に変えればもっと公平な見方ができるようになる、的な。
というか最初の実装自体は終わっていて、それを色々改造していっている。
最初にターミナルでやるコマンドラインアプリとしてあえて実装してるけど、今はフロントを RxJSとjQuery、バックエンドが Django のWebアプリにしてみてる。
こっから React にしたり JS だけで完結したり WebSocket にしたり Swift で iOS に移植したりしたい。あとは新しく勉強する言語でこれを移植したら現実の例としていいかもと思っている。
Swift とかパターンマッチのある言語で書くとここは綺麗そうだなみたいな箇所が結構ある。isinstance 使いすぎで正直汚い。テストもない。
直近ではドラッグドロップとかそういうまともなUIじゃないのでその辺をやっていく。
そういやゲーム状況のオブジェクトをそのままDjangoでキャッシュしてたけど、なぜかサーバを再起動したら一部の属性のデータが消えて「何で?」って思ってた。
原因はクラスの属性に間違ってデータをいれていたことだった。キャッシュできていると思っていたらクラスの属性の方に入っていて、オブジェクトには入ってないからキャッシュに残らない。でもクラスの属性にあるからあたかも値がちゃんと入っているように見える。再起動するとクラスも当然新しく作るから前のデータがない…というからくりだった。
]]>Go の並行処理本、2章のほぼ最後まで読んだ。チャネルとかゴルーチンしか知らないので sync ライブラリの使い方が色々出てきてそういうのもあるんだなーという感じ。 チャネルのブロックの挙動とか一度も読んだことないかあるいはすっかり忘れてる。何となくShenzhen IOのブロックする端子思い出したけどあのイメージであってるんだろうか。
Django の通知系のライブラリ、調べたけど案外サクッと使えそうなものがない。通知タイプに応じてユーザが通知バックエンドを選べるといいけどそのどちらかが欠けてる感じ
Shenzhen IOのソリティアのコマンドライン版大体完成したけどUndoの挙動がおかしいことがある。Pythonistaは実行中の変数の値も見れることに最近気づいたのでスマホでデバッグも頑張ればできるかも
バーガーキングのトリプルチーズワッパー
ブラックフライデーに続いてサイバーマンデーやけど内容同じやんけ
DjangoConの動画見てないな
celery_once うまく動かん
!#2:t … zsh で今うってるコマンドの2番目の引数(フルパス)をファイル名にして展開
Pythonista の Extension 1つ作った。appex.get_url() でとって clipboard.set(val) でクリップボードにいれられる
netlify、bitbucket だとPR出すとプレビュー作られる機能使えないっぽい。ただまあ別ブランチもビルドするように設定しておいてそっちをプレビュー扱いすれば1人で使う分にはよさげ
Pomera で入力したやつはBOMがつくので sed で消せばそのままこのブログのソースとしても使える
電脳コイル何度も見たけどまた見てしまった。何度見てもすばらしい
オライリーのGoの並行のやつ(名前あやふや)読み始めた。今日は読んでないしまだ1章だけ。デッドロックになる条件は4つあって全て満たしたとき。コフマンの条件という
Epos入ると海外保険がついてくる。ただ死亡とか500万まで。結局1600円くらい払って三井海上?かなんかの海外保険にした。リピーター割引があるらしいし
Group Power Oct18 の新曲発表いってみた。32人定員だったけど整理券配布時は満員にならなかったっぽい。次回は休憩が多いかわりに重めがいいらしい。メンバーは大体いつもの人だったな
こぼれいくら丼のミニ。2500円でした
うに！ 800円
PoE2の割引34パーで過去最高だけど多分クリスマスセールあるはず
]]>
