パブリックAPIで（列挙）型を表現する方法

私は自分のクライアントに使用し、将来一般に公開したいシンプルなAPIに取り組んでいます。異なる「タイプ」を持つことができる「アイテム」オブジェクトがあります。型はCの「typedef enum」です。

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

（将来、いくつか追加するかもしれません）

整数として転送するのか、定義された「文字列」として転送するのかを考えています。JSONは次のようになります。

整数の場合：

{
  "name": "The name",
  "type": 0,
   ...
}

文字列の場合：

{
  "name": "The name"
  "type": "boolean"
   ...
}

これにベストプラクティスがあるかどうか疑問に思っています。整数を保持すると、コードが若干単純化され、帯域幅が削減されますが、開発者は文字列を覚えやすくなります。私はプロジェクトに取り組んだことを思い出し、1 = image、2 = audio、3 = htmlを思い出さなければなりませんでした。

あなたが私が考慮すべき他の側面を知っているなら、私はあなたに尋ねています。

文字列を提供します。数字は無意味です。あなたはあなた自身のコードでそれらを使用しないでください（あなたはenum値をラップしています、それは基本的に文字列です）-なぜこれらの数字を使用することでユーザーを罰するのですか？

数値を公開する場合の唯一のプロ-これらを解析する方が簡単です。でもねえ、あなたのことを気にしている人。APIクライアントの世話をします。

文字列を指定すると、クライアントにとって簡単になります。「4は17を支持して廃止された」などのことを言う必要はありません。あなたに代わって構文解析が少し難しくなりますが、それで問題ありません。

両方を提供しないでください：ユーザーとして、私は疑問に思っています

• どちらを使用しますか？両方？[ドキュメントを読む]
• 同じことを言うのに2つの方法があるのはなぜですか？彼らは微妙に違いますか？[ドキュメントを読む]
• 両方を指定し、不一致がある場合はどうなりますか？文句を言う？優先されますか？どれ？[ドキュメントを読む]

ご覧のとおり、理由もなくたくさんのドキュメントを読んでいただいています。

文字列。

Jsonの強みの1つは、人間が読めることです。半年後の出力をデバッグする場合、「0」は何も通知しません。

一部のフレームワークも自動変換を行います。使用していない場合は、自分でコンバーターを作成してコードをドライに保つことができます。

ただし、これは投票になります。

ベストプラクティスは、誰がAPIを使用しているかによって異なります。消費者の生活を楽にするために、APIを消費できるサンプルコードをC、JAVA、iOS、python、rubyで提供する必要があります。これらのラッパーでは、enumを含め、jsonでintを使用してから、jsonを既にenumが設定されたオブジェクトに解析し、このオブジェクトをユーザーコードに返すことができます。

もう1つできることは、両方を提供することです。例えば：

{
  "name": "The name",
  "typeId": 0,
  "type": "ItemTypeBool"
   ...
}

または、apiに最適なものに応じて、typeとtypeStrを使用できます。

そして、これらは冗長であり、アプリケーションに最適なものを選択するのは開発者次第であるとドキュメントに明記します。

ここでjsonを見てください：https : //dev.twitter.com/docs/api/1/get/search Twitterには冗長データ（idおよびid_str）を提供する例がありますが、これは一部のjsonクライアントがJSONの「数値」であり、数字の損失を避けるために文字列が必要です