API設計について、最近得た知見をまとめました。私がGoで開発しているのでGoベースの話になります。
間違いがあればコメントで教えていただければ幸いです。

参考資料

GopherCon 2018 : GopherCon 2018 - How Do You Structure Your Go Apps?
デモのソースコード : katzien/go-structure-examples
クリーンアーキテクチャのソースコード : go-clean-arch
SlackのGophers, StudentGoなどの得た情報
株式会社オージス総研クラウドインテグレーションサービス部 : なぜAPIのアーキテクチャが重要なのか

設計

設計とは

設計は、ユーザー目線で利便性を考える 「インターフェース設計」 と開発者目線で利便性を考える 「アーキテクチャ設計」 があります。「インターフェース設計」で最近多くみられるのはREST APIと言われる設計方法が主流です。また、「アーキテクチャ設計」では、様々なアーキテクチャがあり、自分の開発しているAPIに適したアーキテクチャを使用します。

インターフェース設計

インターフェース設計をする上で考えるべきことは、外部の大多数の開発者向けに開発する LSUDs(Large Set of Unknown Developers) とある特定のアプリケーションのための開発者のための SSKDs(Small Set of Known Developers) の二つのどちらかなのかを明確にすることです。LSUDsでは、RESTなAPI設計が主流です。しかし、SSKDsは、必ずしもRESTなAPI設計に従って開発する必要はありません。開発しているアプリケーションによってAPI設計を考える必要があります。SSKDsで重要なことは、1画面1リクエストを意識することです。

Rest (REpresentational State Transfer)

Rest設計については下記の記事が参考になりました。

翻訳: WebAPI 設計のベストプラクティス

アーキテクチャ設計

アーキテクチャには数多くの種類があります。そのため、どのアーキテクチャを採用するべきか見極めることが大変難しいです。
GopherCon 2018の記事(参考資料)では、このような悩みを持つユーザーのために、アーキテクチャが紹介されていました。
この記事で紹介されている最も簡単なアーキテクチャは、 Flat structure 、 Layered、　Modular です。また、 Domain Driven Development(ドメイン駆動設計)　や Hexagonal Architecture も紹介されています。この記事の他にも、 クリーンアーキテクチャ や オニオンアーキテクチャ などもあります。これらのアーキテクチャの特徴を簡単にまとめたいと思います。

Flat structure

このアーキテクチャは、簡素なAPIに適しているアーキテクチャだと思われます。パッケージ分をせずに全て package main で統一します。そのため規模が大きくなると読みにくいアーキテクチャになると思います。

Layered

このアーキテクチャは、機能ごとにディレクトリを分けています。そうすることで、packegeごとの役割を明確にすることができます。
問題点は、違うディレクトリ同士で値を共有したい場合にどうやって共有するかか問題になります。

Modular

このアーキテクチャは、ハンドラごとにディレクトリを分けています。部品ごとに分けて開発をするので、追加や修正が簡単にできることが良い点だと思います。

その他

他のアーキテクチャは、また別の記事で深くまとめようと思います。

開発しているAPIに合った設計の見つけ方

自分が開発しているAPIは、どのアーキテクチャに向いているのかを見つける方法があります。その方法は、機能が増えたり規模が大きくなったらどこが問題になるかを考えることです。注意点としては、自分のAPIにカッチリ当てはまるアーキテクチャはほとんど無いので、試行錯誤する必要があります。試行錯誤には、かなりの理解が必要なので、「様々なアーキテクチャを実際に使用すること」や「実際に使用されているコードを読むこと」が重要なのではないのかと考えています。

終わりに

記事を書いていて新しく発見した知識も多かったです。自分が使用していたディレクトリ分けは、Layeredアーキテクチャに似ていると感じました。多くのアーキテクチャを学び、適しているアーキテクチャを見つけられるようになりたいです！
ありがとうございました。