APIStudyでAPI開発あるある「やっちまった仕様」編
こんにちは。
今日はアプレッソの脇野さんが主催するAPIStudyにおじゃましてきました。 全員参加型の勉強会で、API開発をしている身としては 毎回あるあるネタが飛び交い、ついつい足を運んでしまいます。
今回も「あるある！」なネタがあったので、自分を戒める意も含めブログに書き起こしてみます。
やっちまった仕様あるある
APIの仕様に統一感がない
例1. パスやパラメータにスネークケースとキャメルケースが混ざっている
例2. 付加情報を追加するパラメータに、add○○=trueやaddDetail=○○が混在している
あるあるすぎて辛い。 仕様の統一感、私が想像するに開発初期の少ないメンバー構成時点では、ドキュメントに起こすまでもないことだと判断しちゃうと思うんですよね。ドキュメント作成するのめんどくさいし管理してかないといけないし。 規模が大きくなって人が増えたり移動したりを繰り返して、メンバーの共通認識がなくなってきたときに起こるんですよね、きっと・・。 対策としては、設計方針を文書にまとめておく、というのが１つあげられるのではないでしょうか。 （面倒くさいところではあるんですけどね）
データの順番が不明確
例. DBから取ってきた値をそのまま返すと、並び順が説明できない
DBを移行したときに困る案件ですねこれは・・。 もしかしたら並び順を担保しなくても良い場合もありそうですが、担保しないといけない場合は、API側で再現できるのだろうか・・。 常に並び順はDBに依存しないようにAPI側で処理を挟んでおくことで、幸せになれそうです。
スペルミス
例. リリース後、パラメータ名がcompanyではなくconpanyになっていることに気づいた
めちゃめちゃ恥ずかしいやつ！！
conpanyはドキュメントからも外して、正しいほうのcompanyをドキュメントに記載してAPIにその口を作れば隠蔽できるんだけど、conpanyの口も残さないといけないから永遠に技術的負債が残る事になる。
レビューしても起こることらしいので（震）、レビューしてれば安心かと思っていたけど、やっぱり人は間違える生き物だってことをあらためて認識しました。スペルミスを教えてくれるlinterをうまく活用できるとある程度防げるかもしれないですね。
まとめ
WebAPIは基本的に、後方互換性を担保する必要があります。 WebAPIを利用するシステムの変更が不要であることを保証するためです。 よって、WebAPIのインターフェースに関わる部分は慎重にしないと、すぐに「互換性のないバージョンにあげたい！」となりますが、互換性のないバージョンをあげる、ということは、二つのバージョンを管理するということなので、泣く泣く今のバージョンでがんばる、といった現状が数多くあると思います（私もその1人です）。 これから新しくWebAPIを開発する人は、上のあるあるネタをアンチパターンとして頭に入れておくことをお勧めします。 「いやいやこんなの常識じゃん。覚えるまでもない」と思ったあなた。ほんとやりがちだから気をつけてね・・・orz
おまけ
初めて新宿のAFURIに行きました。 蒟蒻麺にしておけばよかったな、と食べてから後悔。
