

WebAPIのレスポンスボディにマスターのデータを入れるとき、IDとIDに紐づく値のどちらを返すのがよいのでしょうか？

例えば、あるタスクを取得するGET /tasks/1
のようなWebAPIのレスポンスボディの場合、ステータスのidとnameはどちらを返すのがよいのでしょうか？

### レスポンスボディのサンプル

[code]

    {
     "id": 1,
     "status": {
      "id": 2, // どっちがよい？
      "name": "進行中" // どっちがよい？
    }
    
[/code]

### statusマスターテーブル

id | name  
---|---  
1 | 完了  
2 | 進行中  
3 | 未完了


CC BY-SA 4.0
2023-01-20T08:35:33.937
93476
2023-01-21T05:59:37.607
19297
question
webapi
WebAPIのレスポンスボディに含むマスターの情報はIDかIDに紐づく値か


提示された例から ToDo リストのようなものかと想像しましたが、個人的には id = 数値で返す形式は (利用する側視点で) 分かりづらいと感じます。

最終的には設計の方向性次第かと思いますが、類似の API を参考にしてみるのも一つの方法です。  
Microsoft Graph API では以下の通り、状態を表す文字列を返すようです。

[todoTask resource type - Microsoft Graph v1.0 | Microsoft
Learn](https://learn.microsoft.com/en-
us/graph/api/resources/todotask?view=graph-rest-1.0#properties)

> **Property** | **Type** | **Description**  
> ---|---|---  
> status | taskStatus | Indicates the state or progress of the task. Possible
> values are: `notStarted`, `inProgress`, `completed`, `waitingOnOthers`,
> `deferred`.  
  
もしくは、もっと単純に "完了か否か" のトグルであれば、Remember The Milk では completed というフィールドを用意しています。

[Remember The Milk - Services / API /
Tasks](https://www.rememberthemilk.com/services/api/tasks.rtm)

>
[code]

>             <task id="815784" due="" has_due_time="0"
>             added="2015-05-08T13:52:26Z" completed="" deleted=""
>             priority="2" postponed="0" estimate="" />
>  
[/code]


CC BY-SA 4.0
2023-01-20T12:33:49.623
93480
2023-01-20T12:33:49.623
3060
93476
answer


状況次第です。

・ APIを使うのは誰か。内部だけでしか使わないのか、サードパーティも使うのかとか。  
・APIで得られた結果はどのように使われるのか。プログラムで扱うだけなのか、人間に表示されるのか。後者なのだとしたら多言語対応が必要か。

などなど。

数字がわかりやすい場面もあるしそうでない場面もあります。要件次第ではどちらか一方が自明に決まる場合もあるでしょう。例えば結果を素通しでエンドユーザーに表示する機能しかフロントエンドにないなら自明にメッセージを返さないといえけません。


CC BY-SA 4.0
2023-01-21T05:59:37.607
93488
2023-01-21T05:59:37.607
5793
93476
answer