공개 API에서 (열) 유형을 나타내는 방법

32

나는 내 자신의 클라이언트에 사용하고 향후 대중에게 공개하려는 간단한 API를 개발 중입니다. 다른 "유형"을 가질 수있는 "Item"객체가 있습니다. 형식은 C "typedef enum"입니다.

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

(나중에 일부를 추가 할 수 있음)

정수 또는 정의 된 "문자열"로 전송해야하는지 궁금합니다. JSON은 다음과 같습니다.

정수의 경우 :

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

문자열의 경우 :

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

최선의 방법이 있는지 궁금합니다. 정수를 유지하면 코드가 약간 단순화되고 대역폭이 줄어들지 만 개발자는 문자열을 쉽게 기억할 수 있습니다. 나는 프로젝트에서 일한 것을 기억하고 1 = 이미지, 2 = 오디오, 3 = html을 기억해야했다.

내가 고려해야 할 다른 측면을 알고 있다면 나는 당신에게 묻습니다.

api patterns-and-practices enum

— 줄리앙
소스

사용자가 JSON을 수동으로 자주 편집 할 것으로 예상하십니까?

— James

39

문자열을 제공하십시오. 숫자는 의미가 없습니다. 당신은 자신의 코드에서 그것들을 사용하지 않습니다. 바로 (기본적으로 문자열 인 열거 형 값을 감싸고 있습니다)-왜 사용자 에게이 숫자를 사용해야하는지 처벌합니까?

숫자를 공개하는 경우 유일한 전문가-숫자를 더 쉽게 파싱 할 수 있습니다. 하지만, 누가 당신을 걱정하는지. API 클라이언트를 관리하십시오.

문자열을 제공하면 클라이언트가 더 쉬워집니다. "4는 17을 선호하여 더 이상 사용되지 않았습니다"와 같은 것을 말할 필요는 없습니다. 귀하를 대신하여 약간 파싱하는 것이 좋지만 괜찮습니다.

두 가지를 모두 제공하지 마십시오. 사용자로서 궁금합니다.

어느 것을 사용합니까? 양자 모두? [문서 읽기]
왜 같은 말을하는 두 가지 방법이 있습니까? 그들은 미묘하게 다른가요? [문서 읽기]
둘 다 지정했는데 불일치가 있으면 어떻게합니까? 불평할까요? 우선권이 있습니까? 어느 것? [문서 읽기]

보시다시피, 아무 이유없이 많은 문서를 읽게합니다.

— 일 룩사
소스

@iluxa에 동의합니다

— portforwardpodcast

1

열거 형이 나머지 호출에서 입력으로 예상되는 클래스 (객체)의 멤버라면 어떻게됩니까?

— 종마

2

문자열.

Json의 강점 중 하나는 사람이 읽을 수 있다는 것입니다. 지금부터 반년 출력을 디버깅 할 때 "0"은 아무 것도 알려주지 않습니다.

일부 프레임 워크는 자동 변환도 수행합니다. 하나를 사용하지 않는 경우 코드를 건조하게 유지하기 위해 직접 변환기를 만들 수 있습니다.

그러나 이것은 투표 캐스팅으로 바뀝니다.

— 에브 게니
소스

1

모범 사례는 누가 API를 사용하는지에 따라 다릅니다. 소비자의 삶을 편하게하려면 C, JAVA, iOS, python, ruby로 샘플 코드를 제공해야 API를 사용할 수 있습니다. 이 래퍼에서 열거 형을 포함하고 json에서 int를 사용한 다음 json이 이미 설정된 열거 형을 사용하여 객체로 구문 분석 한 다음이 객체를 사용자 코드로 반환 할 수 있습니다.

당신이 할 수있는 또 다른 일은 둘 다 제공하는 것입니다. 예를 들어 :

{
  "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 클라이언트는 긴 int를 구문 분석 할 수 없기 때문에 json의 "숫자"이며 숫자를 잃지 않도록 문자열이 필요합니다.

— 포트 포워드
소스