WebApiGoodpartsを読んでる

不要なエンベロープ

APIのレスポンスデータとして、こんなレスポンスがよくある

{
    header {
        status:1,
        errCode:0
    },
    body {
        ...実際のデータ...
    }
}

ここで記載している「header」や「body」というのをエンベロープと呼ぶ。
エンベロープは日本語では「封筒」と呼ぶみたい。
同じデータ構造を返すために実際のデータをくるむことを目的としたデータ構造を指す。
で、このエンベロープは不要とのこと。

APIのレスポンスは利用者側からは仕様として既知であり、その情報がheaderにあろうがbodyにあろうが使用したいパラメータはわかるので、余計な構造が1枚挟まれているだけの状態になっているからだと。

こういった形で実装しそうだったから気をつけよっと。

APIで返す日付

フォーマット

APIで返す日付のフォーマットはRFC3339が良いとのこと。
こんなフォーマット。
20018-11-13T12:23:30+09:00
RFC3339はインターネット上で用いる標準形式でもあるとのこと。

自身が作るAPIが何に使われるかによって決めるのがベストかな。

プログラム内で時間操作感はどうなんだろ。
変換のライブラリが用意されてればいいんだけどさくっと検索じゃ見つからなかった。

タイムゾーン

日本向けに公開するなら、"+09:00"つけてもいいけど、インターネットは全世界とつながってるのでUTC標準時の方が良い。
これも対象とするプロダクトによって判断するか。

エラーの表現

ステータスコードで表現

エラーの表現はまずステータスコードで表現すること。
200:成功
300:リダイレクト
400:クライアントサイドに起因するエラー
500:サーバーサイドに起因するエラー
状況に合わせてこれらのステータスコードを使い分ける。
書くステータスコードにも細かく番号が分かれているので、それを使い分ける。
どこにも当てはまらなければ、400や500などざっくりした表現を使うのは有り。

ダメな例として、200でレスポンスしているにも関わらず、レスポンスデータは内部の判定ロジックでパラメータエラーを判定しその内容を返しているみたいな状態はNG。

こういうのも眺めておきたい。

HTTPの仕様を理解しておく

通信料の節約

キャッシュを利用する。
キャッシュは期限切れモデルと検証モデルの2パタンでサーバーから最新データを取得するかを判断する仕組みが存在する。

期限切れモデル

有効期限や現在日時からの経過時間を設定し、その時間間隔を判定して最新情報を取得する場合に使用する。

検証モデル

サーバーの情報が変更されたかを判定して最新情報を取得する場合に使用する。
現在に日時やコンテンツ量から生成したハッシュ値を用いることが多い。

どちらを使うかは実装次第。
天気予報とか、ある程度の時間軸ないで変化しないものは期限切れモデルがよさそう。
検証モデルはコンテンツの変更が頻繁に行われるものがいいかな。
最新情報のニュースを配信するサイトとか、不定期に更新される系かな。

もちろん明示的にキャッシュさせたくない場合にも、制御の仕組みは要されている。

API内での別ドメイへのリクエスト

特定のwebページ内から、別ドメインへのリクエストは仕様上許可されていない。
この許可されてない状況に条件付きで許可できる仕組みがCORS(Cross Origin Resource Sharing)

• ①web画面(https://a.com)
• ②別ドメイン(https://b.com)

①のページ内で②は呼び出せない。これが前述した仕様上の制限。
これを回避するために、①のレスポンスヘッダーでアクセス許可するURIを定義しておけば、②のAPIも実行できるという形になる。

web画面側を実装する際に必要な知識になるかな
利用シーンは多そう。

学びから実装での考慮すること

• 不要なネスト(エンベロープ)は実装しないようにしよう
• 通信料を考慮し、少ない情報で的確な情報を返せるようにしよう
• HTTPのレスポンスコードを適切に使って、「一般的に」使われることを考慮した設計とし、だれが利用しても想定が付くような状態のリクエスト,レスポンスを設計しよう