rest | #iOS | #Android ファショ通

Retrofit は非常に有名なSquare製のJavaで書かれたAndroid 向け HTTP クライアントです。

👉 square/retrofit: Type-safe HTTP client for Android and Java by Square, Inc.

その内部には Kotlin Serialization はサポートされていませんが、オブジェクトのシリアル化のためのコンバータファクトリを追加することができます。独自のコンバータファクトリを作成することもできますし、Jake Wharton が書いたものを使うこともできます。

👉 JakeWharton/retrofit2-kotlinx-serialization-converter: A Retrofit 2 Converter.Factory for Kotlin serialization.

Retrofit2 Converter.Factory を利用するには、ライブラリ dependencies に追加したあと、Retorofit インスタンス生成時に、Extension Function である asConvertFactory を使ってそれを追加します。


val contentType = "application/json".toMediaType()

val retrofit = Retrofit.Builder()
 .baseUrl("https://www.example.com")
 .addConverterFactory(Json.asConverterFactory(contentType))
 .build()

簡単ですね!

ちなみに、.toMediaType() とは、


okhttp3.MediaType.Companion.toMediaType

です。

Kotlin 今どきよくある JSON リクエストからのパース https://t.co/031uPDFOXX #json #プログラミング

— chanzmao (@maochanz) June 9, 2023

👉 「Kotlinx Json」の登場でサードパーティJSONライブラリは不要となる。

REST API の記事は, 今となっては普通にありふれています.

ほとんどのWEBアプリケーションの一部として利用されています.

シンプルで, 一貫性のある, 実用的なインターフェイスが必須で, そうであれば, 他の人が使う場合にかなり簡単にAPIを使うことができます.

これらのプラクティスが当たり前に思うかも知れませんが, よくこれを順守していない人をよく見かけますのでこの投稿を書くことにしました.

これらは RESTful API を設計するときに心に止めておくプラクティスです.

お断り:
これらのプラクティスは私の過去の経験から生まれたものです.
もし, あなたがそうは思わなければ,気軽にメールを送ってください.
そしてそれについて議論しましょう.

APIのバージョン

APIのバージョンは必須にすべきです. これは, 将来, APIの時系列変化の記録となります.

ひとつの方法としてはURLのパス部分にそれを含める方法があります.

/api/v1/...

もうひとつの方法としては, HTTPヘッダ Accept を利用する方法です.
GitHub でも使われています.

バージョンを使うことで, 古いクライアントとの互換性を気にすることなくAPI構造を変更できるようになります.

「動詞」でなく「名詞」を使う

「名詞」でなく「動詞」をリソース名に使っているのをよく見かけます.

悪い例 :

/getProducts
/listOrders
/retreiveClientByOrder?orderId=1

簡潔でわかりやすい構造として「名詞」を使うべきです.
HTTPメソッドを上手に使えばリソース名からアクション部分をなくすことができます.

良い例 :

GET /products : product の全リストを返す
POST /products : product を追加する
GET /products/4 : product #4 を取得する
PATCH/PUT /products/4 : product #4 を更新する

「複数形」を利用する

単数形と複数形のリソース名を混合するのはよくないです.
すぐに混乱して一貫性がなくなります.

アクションが show/delete/update だとしても
/artist は使わず /artists を使う.

GET / HEAD の利用は常にセーフティに使う

RFC2616 では, HEAD / GET メソッドは, 常にセーフティであるべきだと示されています. (ステータスの変更はすべきでない)

悪い例 :

GET /deleteProduct?id=1

検索エンジンのページインデックスを想像してみてください.

リソースのネストを利用する

コレクション内のコレクションを取得したいとき, 簡潔な設計として、ネストされたルーティングを使用します。

特定のアーティストのすべてのアルバムのリストを取得したい場合 :

GET /artists/8/albums

ページング

HTTP上で非常に大きな結果セットを返すことはいい考えではありません。
巨大なJSONをシリアライズすることは高コストとなり, 最終的にパフォーマンスの問題となります.

それを回避するために「ページ分割」が1つの選択肢となります.
Facebook, Twitter, Github などもそうしており,
短時間の複数回の呼び出しは, 一回の巨大な大変遅い実行より大変効果的です.

また, ページネーションを使用している場合にも、リンクのHTTPヘッダーに、
次と前のページのリンクを示しておくことは1つの良い方法です。GitHubもそうしています.

適切な HTTPステータスコードを利用する

コンテンツを返す際には、Success/Error のリクエスト両方に対して必ず適切なHTTPステータスコードを使用して返します.

以下, アプリケーションで利用できるコードの簡単なリストです.

Success codes

201 Created should be used when creating content (INSERT),
202 Accepted should be used when a request is queued for background processing (async tasks),
204 No Content should be used when the request was properly executed but no content was returned (a good example would be when you delete something).

Client error codes

400 Bad Request should be used when there was an error while processing the request payload (malformed JSON, for instance).
401 Unauthorized should be used when a request is not authenticiated (wrong access token, or username or password).
403 Forbidden should be used when the request is successfully authenticiated (see 401), but the action was forbidden.
406 Not Acceptable should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server).
410 Gone Should be returned when the requested resource is permenantely deleted and will never be available again.
422 Unprocesable entity Could be used when there was a validation error while creating an object.

なお, RFC2616 でステータスコードの全リストを見ることができます.