3.1 データフォーマットはどうする?
A.現在の主流は、「JSON」である。
理由は、Web業界で主流のJSやその他の言語で扱いやすいデータ構造であり
シンプルでかつサイズが小さいからである。
時と場合に応じて、「XML」に適用させるデータ構造の方が理想である。
3.1.1 データフォーマットの指定方法
Q.JSON以外のデータフォーマットを扱わなければいけない時はどうする?
A.真っ先に考慮しなければならない時は、「クライアントにどのように取得したい形式を指定させるべきかである。」
EX
クライアントにXMLデータを取得させたい。→どのようにサーバにそれを伝えるべきだろう??
-1 クエリパラメータを使う方法
クエリパラメータを使うURIを用意して、「データ形式を指定する方法である。」
EX
URI
「https://api.example.com/v1/japan?fromat="json"」のような形式をとるパターンである。
-2 拡張子を使う方法
拡張子
「https://api.exaple.com/japan*?user.json*」
拡張子を上記のようにして指定する方法もある。
-3 リクエストヘッダでメディアタイプを指定する方法
リクエストヘッダを扱う方法
EX
------- | ---------------- | --- |
| GET: | /v1/users | |
| Host: | api.example.com | |
| Accept: | application/json | |
Acceptでデータ形式を指定することで、指定したデータ形式の情報を取得できる。
複数指定することができ、順序は左から順番に取得することができる
複数使うなら、メディアタイプを使う方法/一つのパラメータ・・クエリパラメータ
3.4 各データのフォーマット
データ名前のルール
-1 多くのAPIで同じ意味に利用されている。 (わかりやすくするため)
-2 なるべく少ない単語数で表現する (わかりやすくするため)
-3 複数の「単語を連結する場合、その連結方法はAPI全体を通して統一。（説明は省略→単純に わかりにくくなるから)
-4変な省略形は使用しない。 (説明は省略→ 単純に、他者へ通じにくいから)
ただし、APIを社内など限定的に利用する場合は例外として短縮形で利用することがある。あくまでも例外である。
※
※コラム
LSUDsとSSKDSで区分させる。
LSUDSは大規模なAPI→さまざまな開発者にも使ってもらえるようなAPI設計にすることが必須
SSKDSは社内向けなどの規模が限られてるAPI
LSUDSより、SSKDSの方が考慮するポイントは少ない。
性別情報のユースケース
sex「生理的な性別」だと値が数値で表記されることがある。
1男性
2女性
3その他
一方で、genderで表記されることもある、
その際はテキストがたで表記する。
LSUDSは、テキストが好ましい。と言うのも、一目でわかりやすいからである。
-5 単数系、複数形に気を付ける
3.4.3 日付フォーマット
ここでは簡潔に表現・説明する。
LSUDSでは、「**RFC 3339 **」
これまでに日付フォーマ
ットの問題を解決し、読みやすく、使いやすいものを目指してインターネット上で用いる標準形式であるから。
μsまできちんと表記される。
(省略)
3.5レスポンスデータの設計
結論、APIのユースケースごとによく考え、「ユーザが最もシンプルに扱うことができる構造設計を考えた方がベストである。」
APIが不便だと、使いにくいAPIという認識に陥る。クライアントがエラー発生について分かっても
どんなエラーが生じたのか、わからないとどう対応すれば良いかわからなくなるからである。
3.6 エラー表現
では、どんなエラー表現がベストだろうか??
まずはステータスコードが明記されているエラーである。ステータスコードは、今何が起こってるのかわかりやすいデータである。
200, 300,400,500番。それぞれに理由がありわかりやすいため、ステータスコードはポイントである。