アプリエンジニアから見てAPI設計において気をつけてもらえるとうれしいこと

by @mixiappwchr

アプリ向けのAPIの開発時に気をつけてもらえるとうれしい＆メンテナンスや実装コストが下がる点をつらつら書きます。

# データ構造について
* データを返すとき、一定のルールを守って返す。例えば当然ですが同じデータ構造はもちろん、似たような構造もルールを作ってproperty名などそろえておく。relationやlistで返すときもどのデータ構造なのかがpropertyで明確にわかるようなっているようにする
* listを返す場合の形式やpagingが必要な場合の形式はそろえる。配列のデータがない場合も考慮しておく。例えば、データがない場合にNULLにするか or 空配列にする or property自体がないなどきめる
* pagingの場合とか複数のパターンが存在することを覚えておくと幅が広がる。単純なページング or twitterみたいなsince_idなど起点id以上のものを取得するpagingとか。timeline的なものを実装するときはpagingの仕方は検討する。
* 画像を含めサイズが必要なものは、返せるものはサーバーサイドで事前に返してもらえると嬉しい
* エラーレスポンスはちゃんと仕様をきめておく。エラーメッセージもサーバーサイドから返せると楽
* あんまりnestした構造にならないように設計してもらえるとうれしい。デシリアライズ後のデータの扱いが結構煩雑＆理解しづらくなる
* アプリ側でデータの補完をしなくても良くしておく。例えば
* データがない場合,アプリ側でデフォルト値を埋め込むようなコードはなくす。サーバーサイドできちんと返すように修正する。
* あまりなんでも詰め込んだ巨大なレスポンスを返すAPIを切らず、最初はシンプルなAPIを心がける。その状態からサービスの成長やUIのレスポンスをみてパフォーマンスチューニングできるとサーバーサイド側も嬉しいはず。
* 基本的にハッシュや配列形式での設定化できるものは設定化して実装から追い出しておく。あとからリモートからそのままの構造を渡すとリモートからコントロール可能なように作り変えることができる。
    
# アプリ運用時にむけて
* API側の修正だけでできることを多くしておく。例えば
    * API側の変更だけでViewの並び替えができるようにする
        * 配列の並びがかえられるのは当然ですが、例えば複数の枠（おすすめ枠、ランキング枠など存在する場合、それぞれの並びがアプリ側で固定になるよりはサーバーサイドで並び替え自体も指定できるようにすると、枠自体の効果測定の結果を見つつ,A/Bができる。
    * また枠自体も入れ替えができるようにするため、フォーマットをなるべくそろえておくのは当然ですが、データ構造とViewの表現の設計を分離しておくとGood。
        * 例えば毎回コンテンツタイプ増えるたびにViewの数があわせて増えるつくりではなく、そこをうまく分離するとデータ構造増えてもアプリのViewの種別を増やす必要がない And データ構造がViewに密にひもづかないので、Viewだけを入れかえるテストもしやすい。
* 強制、任意アップデート、レビュー促進、メンテナンス、Apple審査中のバージョンか、などなど、サーバーサイドからのresponseでコントロールすることでメンテナンスをサーバー側からすべてできるようにする。
* 追加機能によってはサーバーサイド、アプリの更新タイミングが既存バージョンとの兼ね合いで、シビアになる物があるので機能自体のon/offもサーバーサイドからコントロールすることで、段階的に機能解放したりアプリバージョンを見て柔軟にコントロールができるようにするとより安全に更新ができる。問題が起きたら一時的に機能を閉じることもできる
 
# 負荷対策や利便性向上にむけて
* サーバーサイドのデータのキャッシュ戦略はアプリエンジニアも把握しておく。
    * データの更新頻度やキャッシュ単位を把握しておけば、サーバーサイドのキャッシュだけでなく、クライアントサイドでのキャッシュも活用できる場面がふえてくるはず。ネットワークオフライン時もなるべく見えるようにするとかのためのキャッシュ戦略も考えていける。

# 終わりに
webと違い、iOSであればストアの審査やアプリの更新のタイムラグなどにより、変更がすぐには反映できません。
アプリの種類や、一番メインとなる機能がなんなのか、データの更新頻度はどうなのかによって検討項目やサーバーサイドに寄せるべき点などは変わってきます。
長い目で運用していくにあたっての効率化をいかに盛り込めるかでビジネスのドライブするための手数がだいぶ変わってくるはずです。
自らのアプリ、サービスの長所をより引き出すためのAPI設計を心がけたいですね！

API開発においては下記の記事も書きました

[API開発の効率化の架け橋！APIのStubサーバーを導入して,API開発に効率化、スピード化、柔軟性を手に入れよう！](http://qiita.com/appwatcher/items/49807e72d9600db7196d)


他にもいろいろありますが参考になれば。


##### appwchr post
----

[次世代のスーパーエンジニアたちも学ぶ！マインクラフトで触れる技術たちその1](http://qiita.com/appwatcher/items/05513e170b42b09ecd9a)

[あんなすごいエンジニアともであえるかも？？Qiitaユーザーが集まるSlack Teamを作ってみたよ！](http://qiita.com/appwatcher/items/00faadbf02f691186a54)


[goからiOSまで一人でアプリ開発をしてたらいつの間にかマインクラフトエンジニアになった話](http://qiita.com/appwatcher/items/6c0280cda9c4c8b3c65f)

[Goodbye... Jenkins... Jenkinsを卒業してお手軽CI! iOSもAndroidもCircle CIでアプリのCIを回そう](http://qiita.com/appwatcher/items/4cdf39804d6e46ab7af5)

[まだTestFlight使ってたの？急げ！終了目前のTestFlightから,今すぐにiOSもDeployGateに移行しよう！移行パターンも紹介するよ。](http://qiita.com/appwatcher/items/632460e15fbdb81b7a71)

[Swiftを使ってみて直面した闇。現時点で現場でSwiftを採用すべきかどうかの判断材料](http://qiita.com/appwatcher/items/50295e82ab0095902aaa)

[iOSの開発をする上で絶対に使うべき！外せない！webサービス、開発ツール集【完全版】](http://qiita.com/appwatcher/items/07a3babcb9b6cefb307e)

[iOSでこんなアプリ,こんな機能を作りたかったらこれを見ろ！作りたいアプリに対応するクラス、フレームワーク、ライブラリのまとめ！]
(http://qiita.com/appwatcher/items/b02255026a3ee6d95142)

[注目のiBeacomなどの波に乗り遅れないために！iOSのBluetooth開発を容易にするライブラリを書きました。]
(http://qiita.com/appwatcher/items/7491beffd7260b713542)

[まだまだあった！iOSの開発を劇的に改善する最新のwebサービス、開発ツール集１]
(http://qiita.com/appwatcher/items/f0024fe2ac34da345f04)

[さらに快適なアプリ開発を！iOSの開発をもっと劇的に改善する最新のwebサービス、開発ツール集2]
(http://qiita.com/appwatcher/items/c15d7311e71b4c2b77f1)

[スパゲッティから脱出！iOS開発における遷移の問題をすっきり解決する便利ルーティングライブラリをご紹介]
(http://qiita.com/appwatcher/items/259e8d13fff0547e90af)