SSブログ

API仕様:備忘録(001) [API仕様を書く]

まったく分類・整理していませんが、ランダムにWebサービスのバックエンドのAPI仕様に関する備忘録を書いていきたいと思います。

001 該当する定義が存在しない

問題:あるデータの一覧を返すエンドポイントの仕様に、「返されるデータはXXXYYYStatus順に返される」と記述されているのですが、そもそもXXXYYYStatusはどこにも定義されていない。

この記述を書いた本人は分かっているつもりなのかもしれませんが、第3者が読んだら理解できなくて問い合わせることになります。これは、記述した仕様が第3者が理解できるかという視点を持たないことによるものだと思われます。その視点で、自分で記述した仕様をレビューできる必要があります。

一般的にXXXYYYStatusというのはenumとして定義されている可能性があり、その場合、「XXXYYYStatus順」というのは、具体的に何順なのかが曖昧です。enumの個々の値の型としては、数値(gRPCなど)の場合もあれば、文字列の場合もあります。

XXXYYYStatus順」というのは、おそらく次のことを意味していますが、明確に記述する必要があります。
  • enumとして定義されている順
明確に順序を記述しておかないと、もし、個々の値が文字列であった場合、アルファベット順と解釈される可能性もあります。

Web API設計実践入門──API仕様ファーストによるテスト駆動開発 Web+DB PRESS plusシリーズ

Web API設計実践入門──API仕様ファーストによるテスト駆動開発 Web+DB PRESS plusシリーズ

  • 作者: 柴田 芳樹
  • 出版社/メーカー: 技術評論社
  • 発売日: 2024/07/25
  • メディア: Kindle版

コメント(0)