3分わかるでAPIデザインについて

はじめに

APIの基本から、デザインしていくことの重要性までをサクッと説明していきます。
AWS SUMMIT 2024のステージで紹介されていた内容を参考にしています。
早速解説します！

対象読者

• APIについて知りたい方
• APIデザインについて興味のある方
• API使ったことがある方

目次

1. APIとは
2. APIデザインの重要性
3. 良いAPIデザインとは
4. APIデザインで他に考慮するべきポイント

1. APIとは

APIについて簡単に説明します。
API（Application Programming Interface）は、

アプリケーション同士が情報をやり取りするためのルールやツール

のことを指します。
例えば、、

天気予報アプリが気象データを取得するために気象APIを利用するようなケースなどがあります！

まとまったデータや機能を簡単に使わせていただくことができます！

2. APIデザインの重要性

API開発で課題となるものをPostmanが公開しています。
以下の図からわかるように、最も大きな課題は「人手と時間の不足」ですが、その次に挙げられるのが 「APIデザインスキルの不足」 です。
つまり、APIデザインスキルを身につけると需要のあるエンジニアになれるということです！

引用: https://www.postman.com/state-of-api/executing-on-apis/#obstacles-to-producing-apis-a-unique-challenge-for-big-companies

3. 良いAPIデザインとは

API設計する際に2つのパターンが想定されます。

1. コードやリソースからの設計
2. ユースケースの設計

どちらが良いアプローチでしょうか？

正解は②です！
カスタマーのユースケースから逆算して設計を考えることが重要です。

では、具体的にどのように設計をすれば良いのでしょうか？

実際の例を見て比べると分かりやすいと思うので、ブログに「コメント」や「いいね」をできるアプリを例に考えてみます。

• パターン1: コードやリソースからの設計
• パターン2: ユースケースの設計

パターン1: コードやリソースからの設計

Blog サービスの疑似コードを作成

class Posts {
   createComments() { ... }
   addLikes() { ... }
}

API作成

// ある投稿にコメントをしたい
POST /posts/{post_id}
{"type": "comment", "data": ...}

// ある投稿にLikeをしたい 
POST  /posts/{post_id}
{"type": "likes", "data": ...}

パターン2: ユースケースの設計

APIを設計

// ある投稿にコメントをしたい
POST /posts/{post_id}/comments

// ある投稿にLikeをしたい 
POST /posts/{post_id}/likes

Blog サービスの疑似コードを作成

createCommentOnPost(postId) { ... } likePost(postId) { ... }

4. APIデザインで他に考慮するべきポイント

考えるポイントの一部を箇条書きで整理しました。

• わかりやすいドキュメンテーション
• API スタンダード
  • 標準仕様への準拠
  • スタイルガイド等
• 持続可能性
  • 下位互換性
  • バージョニング
• 非機能要件
  • セキュリティ
  • 性能, 拡張性

おわりに

APIの基本、重要性、設計パターンについて解説しました！
APIデザインを考えるきっかけになれば嬉しいです！