新卒研修の課題として、「swaggerを用いてエンドポイント設計書を作成する」というものがあったのですが、自分はエンドポイントをはじめとしたweb周りの知識が皆無でした。
どのような流れで何を調べてエンドポイント設計書を作成するまでに至ったのかというところを記しておこうと思います。
短期間で調べただけなので、まさかり飛んでくるのを期待してます。

前提

研修課題なので色々と前提条件がありました。

フロントはreact、バックはrailsで実装する
認証システムは自作する(ライブラリはおk

API設計って何に気をつければいいのか

本当になんも分からんの状態だったので、どのようにAPIを設計すれば良いのかが分かりませんでした。
色々ググって参考になった記事としてmicrosoftのRESTful Web APIの設計がめちゃくちゃ参考になりました。
RESTとは何か。というところから設計時に注意すべき点、メソッドの説明などが書かれてあリます。
僕と同じように「なんも分からん」ってなってる人は最初に読むのをお勧めします。

個人的に参考になったのは、この2つの部分です。

リソースは、単一の物理データ項目に基づく必要はありません。たとえば、注文リソースをリレーショナルデータベースの複数のテーブルとして内部的に実装しながら、クライアントには単一のエンティティとして表示することができます。データベースの内部構造を単にミラー化する API は作成しないようにします。 REST の目的は、エンティティと、アプリケーションがそれらのエンティティに対して実行できる操作をモデル化することです。クライアントを内部実装に公開しないでください。

"コレクション/項目/コレクション" よりも複雑なリソース URI を要求しないでください。

「テーブルごとにCRUD用意しておけば良いんじゃね？」とか思ってた自分をぶん殴りたくなります。
どんなエンドポイント設計をすれば使いやすいのか。を考える際に常に意識したいです。

もう1つ参考になった記事としてはWeb API 設計入門も様々な注意すべき点を記載してくれていてためになりました。
APIのルールを統一しよう。みたいな基本的なことからセキュリティ上の注意すべき点などを書いてくれてあります。
ただ、自分の場合は設計書を書くのに時間があまりなかったので全部は対応できてなかったです。

認証、認可ってどうするの？

上記の2つの記事を読んで、なんとなくですがどんな設計をすれば良いのかというイメージは掴めました。
ただ誰でもAPIを叩けるのは困る(当たり前)ので次は認証と認可に関することを調べました。

とりあえず最初に読んでよかったなと思うのがWeb API認証方式のパターンです。
認証と認可の違いから、3つのパターンの認証方式を解説してくれています。

標準化されたHTTP認証方式はBasic認証、Digest認証、Bearer認証、OAuth認証方式についてという記事で詳しく説明してくれていました。

認証周りのお気持ち理解ができました。

仕組みを知っても実装ができなければ意味がないので、railsでどのように実装するのが良いのか。を調べます。
railsのgemでdevise-token-authというものがあります。
実装もなんとかなりそうだったので、認証機能は【Rails API 入門】devise-token-authという記事を参考にしていこうと思います。
設計もこれに合わせました。

swaggerの書き方を調べる

API設計と認証周りのお気持ちが理解できたので、実際にswaggerで設計書を書きます。
バージョンは古いですが、とりあえずSwaggerの記法まとめを読みました。
これを読んで雰囲気が掴めたら、あとは公式のドキュメントをみながら書いていきます。
swagger editorが便利ですね。

余談ですが、swaggerの記法を調べるときに日本語でググると情報あんま出てこなかったので、英語でググることをお勧めします。

最後に

特に中身のない記事になって申し訳ないですが、紹介した記事を順番に読んでいくと基本的な事柄は理解できると思います。
いろんな人が書いてくれた素晴らしい記事に感謝です。