iOS/Androidアプリにおける
APIサーバーのいろは

YAPC::Hokkaido 2016.12.10 Sat @札幌市産業振興センター
Yuji Shimada (@xaicron)

いろいろと API を作って来た自分がここ数年
iOS/Android アプリ向けの API を作るにあたって考えたことを発表します。

すべての API は SSL にすべし！

2016 end らへんからiOS は App Transport Security (ATS) によって SSL にすることが推奨されている

実際にはアプリ申請の際に詳細な理由を書くことにより、審査を通過する可能性はある

HTTP/2 の台頭により、今後 SSL 化の波は避けて通れない
SSL ではない通信は内容の傍受が容易でありセキュアとは言い難い

ユーザーに安心して利用してもらいたい！

すべての API は SSL にすべし！

SSL アクセスで利用するプロトコルはどうするか？

現時点では HTTPS でよいと考えている

理由

相当なハイトラフィックではない限り、独自プロトコルにするメリットがない
知見が豊富
将来的に HTTP/2 にし易い

よくある質問

Q. HTTPS にしたらアクセス遅くないですか？

A. 一概には言えませんが、HTTP に比べたらハンドシェイクに時間がかかるケースが多いです。
しかし先述したように iOS からのリクエストはすべて ATS に準拠することが推奨されています。

よくある質問

Q. HTTPS にしたらフロントサーバーの負荷やばそう

A. SSL アクセラレータを買いましょう。
またはそれに準ずるなにかを利用するのがベターです。
(nginx + ssl cache on memcached 的なものとか)

よくある質問

Q. HTTPS にしたらフロントサーバーの負荷やばそう

A. SSL アクセラレータを買いましょう。
またはそれに準ずるなにかを利用するのがベターです。
(nginx + ssl cache on memcached 的なものとか)

もし、そういったものが利用できない場合でも、数年前に比べてハードウェアの性能が上がっていますので、SSL の処理が重くて死ぬ！みたいなことが発生するケースは減っているのではないかと思います。（要出典）

よくある質問

Q. え、API のアプリケーションサーバー自体も HTTPS に対応しないといけないの？

A. SSL アクセラレータまたはそれに準ずるなにかが HTTP にしてプロキシーすればいいので、イントラ内では不要と考えています。

よくある質問

Q. 現時点で HTTP/2 じゃないの？
A. もちろん HTTP/2 でもいいです。（将来的にはそうなるでしょう）
iOS9 からは NSURLSession が、Android では OkHttp が対応しています。
でも iOS8 をサポートする場合は別途 HTTP Client を選定する必要があるでしょう。

まとめ

今後 SSL ではないことによるデメリットのほうが多くなっていくと思われますし、数年前に比べてもサーバーの性能は上がっており、ソフトウェアも改善されていっているので、早めに SSL 化をしてドヤりましょう

APIの認証について

正規のアプリのみからのアクセスのみを許可したい
API サーバーからは、誰からのアクセスなのかを知りたい

というのが基本的な要件になります

認証にはJWTを利用

JWT とは？

JSON Web Token (RFC7519) のこと。

ざっくりいうと JSON を Base64 URL Encode してかつ署名を付けられるというもの

多数の言語でライブラリがあり、簡単に利用可能
Google の OAuth2.0 などでも利用されている

Perl だと拙作の JSON::WebToken があります。

JWTとは

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ6aWdvcm91IiwiZm9vIjoiYmFyIiwiZXhwIjoxNDgxMjExNzk4fQ.NQMMtnMK9L2JX6-7mheTGvUjMt9Vksq9RyX4GrKdbe0

みたいな文字列

JWTとは

Header, Claims, Signature の 3つで構成されている
ドット区切りになっている
それぞれが base64 url encode されている
base64 url encode されているため、HTTP Header に利用することが容易

JWTとは

Header をもとにどのような JWT を作成するかを決める
Claims はいくつかの予約キーワードが存在するが、それ以外は自由に値を入れることができる
Signature を検証することで JSON が改ざんされていないことを保証できる

JWTとは

# Header
{"alg":"HS256"}
# Claims
{"iss":"nekokak","foo":"bar"}

を secret で署名すると

eyJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJuZWtva2FrIn0.e1zHN8T8VkS8GYddVF3CJeJ5QyrXKQgG3x6AuuWOp18

のようになる

JSON::WebToken で書くと以下のような感じ

my $jwt = JSON::WebToken->encode(
  { iss => 'nekokak', foo => 'bar' }, # Claims
  'secret',                           # secret
  'HS256',                            # alg (デフォルトがHS256なので省略可)
);

JWTを認証に利用する

JWT を HTTP Header に入れてアプリから API リクエストを行う。このとき、JWT の Claims に認証情報をいれる。

例えば

ユーザーの識別子 (user id 的なもの)
OS の種類 (iOS or Android)
アプリのバージョン (v1.2.3 など)

などを送ることで、JWT を検証するのみで、ユーザーの認証が可能になります。

JWTを認証に利用する

実際の利用ケースとしては以下のように Authorization ヘッダーにぶっこむなどする
と良いでしょう。

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIiLCJpc3MiOiJuZWtva2FrIn0.e1zHN8T8VkS8GYddVF3CJeJ5QyrXKQgG3x6AuuWOp18

まとめ

JWT を HTTP Header に入れることで、認証が可能
Claims に OS種別や、アプリのバージョンなどを入れることで、サーバー側で処理の切り替えなどが容易になる

JSON-RPCの利用

オレオレ JSON 形式で送るのでもいいけど、必要最低限の仕様が盛り込まれている

正常系とエラー系のレスポンスフォーマットが決まっている
ある程度エラーコードが規定されている

似たようなものに MessagePack RPC があるけれど、人間が読めないので。。。
社内で JSON-RPC の WAF を作っていてすでに様々なサービスで利用していてこなれてた

JSON-RPCとは

リクエスト形式は以下のようなもので

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "method": "someMethod",
    "params": { ... }
}

レスポンスは以下のような感じ

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "result": { ... }
}

JSON-RPCとは

たとえば、getTweet のような API があったとしたら

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "method": "getTweet",
    "params": {
       "tweetId": "123456789" # ツイートのユニークな ID をしていする
    }
}

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "result": { # ツイートオブジェクトが返ってくる
       "tweetId": "123456789",
       "screenName": "xaicron",
       "tweet": "お前はいままで逃した終電の数を覚えているか？",
       ...
    }
}

のような感じになるでしょう。

エラーケース

リクエスト形式は以下のようなもので

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "method": "someMethod",
    "params": { ... }
}

レスポンスは result がなくて error が返ってくる

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "error": {
       "code": -32600,
       "message": "Invalid Params"
    }
}

JSON-RPC over HTTP

さて、JSON-RPC は通信プロトコルまでは定義されていません。
HTTPS で通信することを決めましたので、HTTP プロトコル上で JSON-RPC を使う事になります。

JSON-RPC over HTTP？

あれ、でも HTTP にもエラーステータスあるよな？
JSON-RPC のエラーコードと合わせたほうがいいのかな？
RESTFul っぽくやったほうがいいかな？

JSON-RPC over HTTP？

たとえば、Invalid Params を例に上げると

400 Bad Request

{
    "id": "foo",
    "jsonrpc": "2.0",
    "error": {
       "code": -32600,
       "message": "Invalid Params"
    }
}

みたいな感じでしょうか？

JSON-RPC over HTTP？

たとえば、Invalid Params を例に上げると

400 Bad Request # <- HTTP Status

{
    "id": "foo",
    "jsonrpc": "2.0",
    "error": {
       "code": -32600, # <- JSON-RPC Error Code
       "message": "Invalid Params"
    }
}

なんかエラーコードが2つあるぞ...!!!

JSON-RPC over HTTP

アプリ側からは

HTTP Status は HTTP リクエストが成功したか否かのみに利用する
HTTP Status が 200 の場合のみ JSON-RPC の解析を試みるようにする

JSON-RPC over HTTP

アプリ側からは

HTTP Status は HTTP リクエストが成功したか否かのみに利用する
HTTP Status が 200 の場合のみ JSON-RPC の解析を試みるようにする

-> この2つのルールを守るだけでアプリ側のエラー処理がものすごく簡単になる！

JSON-RPC over HTTP

たとえば

クライアントエンジニア (以下ク): なんか 401 返ってくるんだけど？

JSON-RPC over HTTP

たとえば

クライアントエンジニア (以下ク): なんか 401 返ってくるんだけど？
サーバーエンジニア(以下サ): 社内ネットワークじゃないと Basic 認証かかってるよー

JSON-RPC over HTTP

たとえば

ク: 502 が返ってくるんだけど？
サ: サーバー落ちてた、正直すまんかった

JSON-RPC over HTTP

たとえば

ク: 400 が返ってくるんだけど？
サ: ドメインとかパスとかあってるンゴ？

まとめ

データの送受信は JSON-RPC に則りましょう
API からのレスポンスでは、HTTP Status は 200 のみ返しましょう
リクエストのエラー処理は JSON-RPC の仕様を考慮するのみで OK

すべての API が同じ速度、同じリソース使用率、同じリクエスト数であることはまず無いので、APIごとに負荷を分載したいというニーズが自ずと出てくるかと思います。

JSON-RPC でいうと method 単位で切り分けたいですね。

method単位で振り分けたいとき

JSON-RPC over HTTP ではリクエストボディをパースして method を得る必要があります。

{
    "id": "xxxxx",
    "jsonrpc": "2.0",
    "method": "vearyHevyMethod", # この method は専用のサーバーに振り分けたい！
    "params": { ... }
}

method単位で振り分けたいとき

通常、API のアプリケーションサーバーが直接クライアントアプリからリクエストを受
け付けるのではなく、nginx や Apache などのフロントサーバーが存在していると思います。

愚直やるとリクエストボディを、フロントサーバーで JSON-RPC の解析をしなくてはいけなくて若干イケてません。

URLで分けちゃう

具体的にいうと以下のような形式にします。

https://api.example.com/{version}/{method}

URLで分けちゃう

例えば以下のような形式にします。

https://api.example.com/{version}/{method}

URLで分けちゃう

例えば以下のような形式にします。

https://api.example.com/{version}/{method}

フロントで以下のような URL を受けられるようにすることで、それぞれの API のエンドポイント毎にリクエストを振り分けることが可能になります。

https://api.example.com/v1.0/getBestSpeakerAward

API種別毎にアクセスを分散したい

ただし、愚直にエンドポイントを追加していく方法だと、フロントと API 両方を変更する必要があるので、インフラエンジニアの人とあれこれしないと行けないですね。

API種別毎にアクセスを分散したい

ベースとして以下のようにワイルドカードで指定しておいて、必要なやつから徐々に分散していくのが良いでしょう

例えば nginx だったら

location ~ ^/v\d+.\d+/getBeer$ { proxy_pass http://beer.example.com/; }
location ~ ^/v\d+.\d+/.+$      { proxy_pass http://all.example.com/; }

のような感じにしておけばカジュアルに method が追加できて便利ですね。

クライアント側ではどうするの？

version + method で URL を自動生成するようにしておけば、新しい method を追加したときでも何も気にせずにこの仕組に乗れるのでとっても簡単です！

まとめ

URL ベースの L7 分散が取り急ぎ運用簡単で便利
バージョンごとだったり、API の種類だったりで簡単に振り分けることが可能
ある日突然負荷が増えた API とかでも、フロントの設定だけで負荷を分散できる

そのあとちゃんと API とクライアントをいい感じにしないとダメですよ！

ただ、今後はオンプレでこういうのを考えることは減っていくと思いますし、「それクラウドでｗ」という「それクラ」も増えていくでしょう。(というかそうなっている。)

だいたい2014年ぐらいに考えて実装した仕組みですが、だいたい現在もクラウドでマイクロサービスあんじゃ〜！って感じでそんなに当時考えていたことを未来がずれてなかったな〜という感じです。

とはいえ今後は API サーバーを自分で作るとかなくなっていくと思いますし、よりサービスを良いサービスを作る方向にフォーカスしやすくなっていって良い世の中だなって思いました！（小並感）

j or →: next

k or ←: prev

h or ↑: list

l or ↓: return

o or ↵: open

? or /: toggle this help

iOS/AndroidアプリにおけるAPIサーバーのいろは

今日のアジェンダ

すべての API は SSL にすべし！

すべての API は SSL にすべし！

すべての API は SSL にすべし！

すべての API は SSL にすべし！

よくある質問

よくある質問

よくある質問

よくある質問

よくある質問

よくある質問

よくある質問

よくある質問

まとめ

APIの認証について

認証にはJWTを利用

JWTとは

JWTとは

JWTとは

JWTとは

JWTを認証に利用する

JWTを認証に利用する

まとめ

JSON-RPCの利用

JSON-RPCとは

JSON-RPCとは

JSON-RPCとは

エラーケース

JSON-RPC over HTTP

JSON-RPC over HTTP？

JSON-RPC over HTTP？

JSON-RPC over HTTP？

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

JSON-RPC over HTTP

まとめ

method単位で振り分けたいとき

method単位で振り分けたいとき

URLで分けちゃう

URLで分けちゃう

URLで分けちゃう

URLで分けちゃう

API種別毎にアクセスを分散したい

API種別毎にアクセスを分散したい

クライアント側ではどうするの？

まとめ

iOS/Androidアプリにおける
APIサーバーのいろは