YOUTRUST WebチームのAPI設計例の紹介

こんにちは！YOUTRUSTでWebエンジニアをしている大竹（YOUTRUST）です。

9月も中旬ですが、まだまだ残暑が続いていますね。引き続き体調管理に気をつけていきたいと思います。

本日のテーマ

以前のブログで開発フローについて軽く触れたのですが、本日はその内容を掘り下げて、API設計（設計書）についてお話しします。

tech.youtrust.co.jp

設計書の作成について

前提として設計書は以下の目的で作成しています。

実装後のコードレビューで大きな手戻りが発生しないようにする

コードレビューでエンドポイントの変更などが発生すると、大きな手戻りになってしまい、実装が無駄になってしまう可能性があります。 そのため、設計のタイミングでエンドポイント等を事前にレビューすることで、大きな手戻りが発生しないようにしています。

設計内容を元に細かいタスクに分割することで実装に着手しやすくする

設計は細かいタスクに分割できるように意識して行っています。これにより、たとえ設計者と実装者が異なっていても、滞りなく実装ができるようにしています。

設計書は作成が完了したらレビューするようにしており、2 Approve制を取り入れています。

API設計書の例

弊社で作成しているAPI設計書の例を記載します。

弊社ではAPIの作成にCQSアーキテクチャを採用しています。そのため、参照系と更新系でAPI設計書の書き方が異なるので、参照系と更新系のAPI設計書例をそれぞれ記載します。

※弊社のCQSアーキテクチャの詳細についてはこちらをご参照ください。

参照系の場合

ユーザー一覧取得APIを例に記載します。

APIインターフェースの定義

  • エンドポイント
    • GET /api/users
  • クエリパラメータ
    • search_word（検索ワード）
  • レスポンス
    • 正常系
      • ステータスコード
        • 200
      • レスポンスボディ（JSON形式）
        • { "users": [{ "id": [ユーザーのID], "name": [ユーザー名], ... }, ... ] }
    • 異常系
      • ステータスコード
        • 401
          • 未認証の場合

Controllerの定義

  • クラス名
    • Api::UsersController
  • メソッド名
    • index
  • 処理内容
    • User::SearchUsersQuery.runを実行して対象ユーザー一覧を取得
    • 取得したユーザー一覧をもとにJSONを返却

Queryの定義

  • クラス名
    • User::SearchUsersQuery
  • 引数
    • search_word（検索ワード）
  • 処理内容
    • search_wordと名前が一致するユーザー一覧を返却する

更新系の場合

ユーザー更新APIを例に記載します。

APIインターフェースの定義

  • エンドポイント
    • PATCH /api/users/:user_id
  • パスパラメータ
    • user_id（ユーザーのID）
  • リクエストボディ
    • { "user": { "name": [新しいユーザー名], ... } }
  • レスポンス
    • 正常系
      • ステータスコード
        • 200
      • レスポンスボディ（JSON形式）
        • { "user": { "id": [ユーザーのID], "name": [ユーザー名], ... } }
    • 異常系
      • ステータスコード
        • 400
          • 不正なリクエスト（バリデーションエラーなど）の場合
        • 401
          • 未認証の場合
        • 404
          • 指定のユーザーが存在しない場合

Controllerの定義

  • クラス名
    • Api::UsersController
  • メソッド名
    • update
  • 処理内容
    • User::UpdateUserUseCase.runを実行してユーザー情報を更新
      • UseCaseが成功した場合
        • HTTPステータスコード200で、更新したユーザー情報のJSONを返却
      • UseCaseが失敗した場合
        • HTTPステータスコード400を返却

UseCaseの定義

  • クラス名
    • User::UpdateUserUseCase
  • 引数
    • operation_user（操作ユーザー）
    • target_user（更新対象ユーザー）
    • new_name（新しいユーザー名）
  • 処理内容
    • バリデーションを実行
      • operation_userとtarget_userが同じユーザーである
    • operation_userに対してロックを取得
    • User::UpdateUserCommand.runを実行してユーザー情報を更新
      • Commandが成功した場合
        • 更新後のユーザー情報を返却
      • Commandが失敗した場合
        • ロールバックを実行

Commandの定義

  • クラス名
    • User::UpdateUserCommand
  • 引数
    • target_user（更新対象ユーザー）
    • new_name（新しいユーザー名）
  • 処理内容
    • バリデーション
      • 新しいユーザー名の文字数が3文字以上20文字以下である
    • target_userの名前をnew_nameに更新

まとめ

今回は弊社のAPI設計例を紹介させていただきました！

設計書を作成することで、大きな手戻りを防ぐことができたり、実装に着手しやすくなったりと、様々なメリットを享受できています。

ぜひ弊社のAPI設計例を参考にしてもらえたら嬉しいです！

最後に

弊社YOUTRUSTではエンジニアを積極的に採用しています！

Webエンジニアだけでなく、アプリエンジニアやSREエンジニアなど、様々なポジションで求人を出しておりますので、ぜひご応募ください！

herp.careers