ざっくりイメージしかなかったので一通り読んで、流れがわかりました。

API設計は、UI/UXの設計と実は相性がいい

UIと同様に、APIは、そのユーザーがその目標、すなわちゴールを達成する手助けを、ユーザー中心(APIを呼ぶ側)に考えて設計するという意味で、根本思想が同じ。

public api(製品など外向け)とprivate api(自分達only)の違い

この2つの違いは、APIがどのように提供されているかではなく、誰に対して提供されているか

APIは実装を隠すために作られる

言い換えれば、ソフトウェアの動作の仕組みに焦点をあてるのではなく、ユーザーがやりたいことに焦点を合わせて設計することが大原則。その結果が、APIの実装は隠されることに繋がる

内部の細いビジネスロジックは、api使用者には関係ないことがあるので、そのあたりの処理はひとつにまとめて実装を隠し、わかりやすくしよう。

APIゴールキャンパス

ユーザーがやりたいことをゴールから逆算して埋めていくと、APIで必要な機能要件の前提が揃う

ゴールキャンパスは段階的、反復的なプロセス

チリも積もれば山となる。ページごとなどで少しずつ洗い出していこおう。

REST APIの基本的な流れ (APIゴールキャンパスをREST APIに置き換える)

複数形の名前を使うのがRESTの慣習

× /product ○ /products

ゴールごとに欲しいデータを定義する

DB設計も、このあたりから一緒にいじりながら適切なものを作っていく。

APIの設計も作りながら継続的に改善していく

ゴール -> メソッド -> APIと繋がる

OAS(Open API Specification)はREST API記述フォーマット

2016年にSwaggerからOASに名称変更

OAS作るタイミングは、APIキャンパスつくって、それをどうREST APIで作るか頭にざっくりあったらOK

情報的価値のあるエラーフィードバックを洗い出して返す

二つの形式エラーは、ひとつにまとめて返すべきである。

データの一貫性

URLレベルの一貫性

コンテンツネゴシエーション

単一のレスポンスを様々な表現で交換できるようにするHTTPメカニズム。Content-Typeでサーバー側は返すが、APIを要求する側もAcceptリクエストヘッダーで指定できる。

言語変換をコンテンツネゴシエーションを使って変更する

jsonデータの整形

プロパティの数が20を超えたら、多すぎないか考えるべき、またjsonのネストも三つを超えたらちょっと立ち止まって考えよう。

cyber-s / blog

[会社本] Web APIの設計 #877