API에서 JSON 응답을 구성하기위한 표준 또는 모범 사례가 있습니까? 분명히 모든 응용 프로그램의 데이터가 다르므로 관심이있는 것이 아니라 오히려 "응답 상용구"입니다. 내가 의미하는 것의 예 :

성공적인 요청 :

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

실패한 요청 :

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

그렇습니다. 몇 가지 표준이 있습니다 (표준 정의에 대한 자유는 있지만).

1. JSON API -JSON API는 응답뿐만 아니라 리소스 생성 및 업데이트도 포함합니다.
2. JSend- 단순하고 아마도 당신이 이미하고있는 것.
3. OData JSON 프로토콜 -매우 복잡합니다.
4. HAL -OData와 유사하지만 HATEOAS 와 같은 것을 목표로합니다 .

JSON API 설명 형식도 있습니다.

• 뽐내며 걷기
  • JSON 스키마 (스웨거에서 사용되지만 단독으로 사용할 수 있음)
• JSON의 WADL
• 라멜
• 이론상 HATEOAS 가 자기 설명 이기 때문에 HAL .

Google JSON 가이드

성공 응답 반환 data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

오류 응답 반환 error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

클라이언트가 JS 인 if ("error" in response) {}경우 오류가 있는지 확인할 수 있습니다 .

나는 사실상의 표준이 실제로 나오지 않았다고 생각한다. 그러나 상관없이 여기에 내 테이크가 있습니다.

성공적인 요청 :

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

실패한 요청 :

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

장점 : 성공 사례와 오류 사례 모두에서 동일한 최상위 요소

단점 : 오류 코드는 없지만 원하는 경우 상태를 (성공 또는 실패) 코드로 변경하거나 "code"라는 다른 최상위 항목을 추가 할 수 있습니다.

REST 웹 서비스 디자인에 대한 질문과 성공 / 오류에 대한 질문이 있다고 가정합니다.

디자인에는 3 가지 유형이 있다고 생각합니다.

1. HTTP 상태 코드 만 사용 하여 오류가 있는지 표시하고 표준 오류로 제한하십시오 (보통 충분해야 함).

   • 장점 : API와 독립적 인 표준입니다.
   • 단점 : 실제로 일어난 일에 대한 정보가 적습니다.

2. HTTP Status + json body를 사용하십시오 (오류 인 경우에도). 오류 (예 : 코드, 메시지, 이유, 유형 등)에 대해 균일 한 구조를 정의하고 오류에 사용하십시오. 성공한 경우 예상 json 응답을 반환하십시오.

   • 장점 : 기존 HTTP 상태 코드를 사용하고 오류를 설명하는 json을 반환 할 때 여전히 표준입니다 (발생한 상황에 대한 자세한 정보 제공).
   • 단점 : 출력 json은 오류 또는 성공 여부에 따라 달라집니다.

3. http 상태 (예 : 항상 상태 200)를 잊어 버리고 항상 json을 사용하고 응답의 루트에 부울 responseValid 및 오류 인 경우 채워지는 오류 객체 (코드, 메시지 등)를 추가하십시오. 그렇지 않으면 다른 필드 (성공)이 채워집니다.

   • 장점 : 클라이언트는 json 문자열 인 응답 본문 만 처리하고 상태 (?)를 무시합니다.

   • 단점 : 표준이 적다.

선택하는 것은 당신에게 달려 있습니다 :)

API에 따라 2 또는 3을 선택합니다 (json rest apis에는 2를 선호합니다). REST Api를 디자인 할 때 경험 한 또 다른 것은 매개 변수, 본문, 응답, 헤더 등의 각 리소스 (url)에 대한 설명서의 중요성입니다.

저지 (jax-rs 구현) + genson (java / json 데이터 바인딩 라이브러리) 을 사용하는 것이 좋습니다 . 클래스 패스에 genson + jersey를 드롭하면 json이 자동으로 지원됩니다.

편집하다:

• 솔루션 2는 구현하기가 가장 어렵지만 이점은 비즈니스 오류뿐만 아니라 예외를 잘 처리 할 수 ​​있다는 것입니다. 초기 노력이 더 중요하지만 장기적으로이기는 것입니다.

• 솔루션 3은 서버 측과 클라이언트 모두에서 구현하기 쉽지만 responseValid + 오류도 포함하는 응답 객체에 반환하려는 객체를 캡슐화해야하기 때문에 좋지 않습니다.

RFC 7807 : 문제점 세부 사항 HTTP API의이 순간에 우리가 공식 표준이 가장 가까운 것입니다.

다음은 Instagram에서 사용하는 json 형식입니다.

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

나는 이것이 표준이라고 주장하기 위해 오만한 것이 아니므로 "나는 선호한다"형식을 사용할 것이다.

나는 간결한 응답을 선호합니다 (/ articles 목록을 요청할 때 기사의 JSON 배열을 원합니다).

내 디자인에서 상태 보고서에 HTTP를 사용하고 200 은 페이로드 만 반환합니다.

400 은 요청의 문제점에 대한 메시지를 리턴합니다.

{"message" : "Missing parameter: 'param'"}

404를 반환모델 / 컨트롤러 / URI가 존재하지 않으면

내 쪽에서 처리하는 동안 오류가 발생 하면 메시지와 함께 501 을 반환 합니다.

{"message" : "Could not connect to data store."}

내가 본 것에서 REST-ish 프레임 워크는이 라인을 따르는 경향이 있습니다.

근거 :

JSON은 페이로드 형식 이어야 하며 세션 프로토콜이 아닙니다. 장황한 세션 기반 페이로드에 대한 전체 아이디어는 XML / SOAP 세계와 이러한 부풀린 디자인을 만든 다양한 잘못된 선택에서 비롯됩니다. 우리가 모든 것이 엄청난 두통이라는 것을 깨달은 후 REST / JSON의 요점은 그것을 KISS하고 HTTP를 준수하는 것입니다. JSend 에는 원격 표준 이 있다고 생각하지 않으며 특히 더 자세한 정보는 없습니다. XHR은 HTTP 응답에 반응합니다. AJAX에 jQuery를 사용하는 경우 (대부분의 경우처럼) try/ catch및 done()/ fail()콜백을 사용하여 오류를 캡처 할 수 있습니다 . JSON으로 상태 보고서를 캡슐화하는 것이 그보다 더 유용한 방법을 알 수 없습니다.

가치있는 일을 위해 나는 이것을 다르게합니다. 성공적인 호출에는 JSON 객체 만 있습니다. true를 나타내는 성공 필드와 JSON 오브젝트가있는 페이로드 필드를 포함하는 상위 레벨 JSON 오브젝트가 필요하지 않습니다. 200으로 적절한 JSON 객체를 반환하거나 헤더의 HTTP 상태에 대해 200 범위에서 적절한 것을 반환합니다.

그러나 오류 (400 제품군의 무언가)가 있으면 올바르게 구성된 JSON 오류 객체를 반환합니다. 예를 들어, 클라이언트가 이메일 주소와 전화 번호를 사용하여 사용자를 POST하고 있고 그 중 하나가 잘못된 경우 (예 : 기본 데이터베이스에 삽입 할 수없는 경우) 다음과 같이 반환합니다.

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

여기서 중요한 것은 "field"속성이 확인할 수없는 JSON 필드와 정확히 일치해야한다는 것입니다. 이를 통해 클라이언트는 요청에 무엇이 잘못되었는지 정확하게 알 수 있습니다. 또한 "메시지"는 요청의 로캘에 있습니다. "emailAddress"및 "phoneNumber"둘 다 ​​유효하지 않은 경우 "errors"배열에는 두 항목 모두에 대한 항목이 포함됩니다. 409 (충돌) JSON 응답 본문은 다음과 같습니다.

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

클라이언트는 HTTP 상태 코드와이 JSON을 사용하여 결정적인 방식으로 오류에 응답하는 데 필요한 모든 것을 갖추고 있으며 HTTP 상태 코드 교체를 완료하는 새로운 오류 표준을 만들지 않습니다. 이 오류는 400 오류 범위에서만 발생합니다. 200 범위의 모든 것에 대해서는 적절한 것을 반환 할 수 있습니다. 나에게 그것은 종종 HAL과 같은 JSON 객체이지만 실제로는 중요하지 않습니다.

내가 추가하려고 생각한 것은 "오류"배열 항목이나 JSON 객체 자체의 루트에있는 숫자 오류 코드였습니다. 그러나 지금까지는 필요하지 않았습니다.

구글, 페이스 북, 트위터, 아마존 등의 거대 소프트웨어 거인들의 나머지 API 응답 형식에 대해서는 동의하지 않지만, 일부 사람들이 응답 형식을 표준화하려고 시도한 위의 답변에 많은 링크가 제공되었습니다.

API의 요구 사항이 다를 수 있기 때문에 모든 사람이 탑승하고 어떤 형식에 동의하는 것은 매우 어렵습니다. API를 사용하는 수백만 명의 사용자가 있다면 왜 응답 형식을 변경 하시겠습니까?

다음은 Google, Twitter, Amazon 및 인터넷의 일부 게시물에서 영감을 얻은 응답 형식에 대한 내용입니다.

https://github.com/adnan-kamili/rest-api-response-format

스와 거 파일 :

https://github.com/adnan-kamili/swagger-sample-template

JSON의 요점은 완전히 역동적이고 유연하다는 것입니다. 단일 노드에 뿌리를 둔 일련의 JavaScript 객체와 배열이기 때문에 원하는대로 구부릴 수 있습니다.

루트 노드의 유형은 사용자에게 달려 있으며, 포함 된 것은 응답과 함께 메타 데이터를 보내는 것이 귀하에게 달려 있으며, mime 유형을 설정했는지 application/json또는 text/plain귀하가 원하는 대로 남겨 두 었는지 ( 가장자리 케이스를 처리하는 방법을 알고 있다면).

원하는 간단한 스키마를 작성하십시오.
개인적으로, 나는 발견 한 것을 분석 추적 및 MP3 / OGG 제공 및 이미지 갤러리 제공 및 텍스트 메시징 및 온라인 게임을위한 네트워크 패킷 및 블로그 게시물과 블로그 - 코멘트 모두 가 매우 다른 요구 사항 이 무엇인지의 관점에서가 발송 및 수령 대상 및 소비 방법

따라서 내가 원하는 모든 것은 XML2.0 또는 그와 같은 것을 기반으로 동일한 상용구 표준을 준수하는 것입니다.

즉, 당신 에게 이해되고 잘 생각 되는 스키마를 사용하는 것에 대해 말해야 할 것이 많이 있습니다 .
API 응답을 읽고, 좋아하는 것을 기록하고, 싫어하는 것을 비판하고, 그 비판을 적어 놓고 왜 그들이 당신을 잘못된 길로 인도했는지 이해 한 다음, 배운 것을 적용하는 방법에 대해 생각하십시오.

JSON-RPC 2.0 은 표준 요청 및 응답 형식을 정의하며 REST API를 사용한 후 신선한 공기를 마시 게됩니다.

나중에 오는 사람들을 위해 HAL, JSend 및 JSON API를 포함하는 허용되는 답변 외에도 다음과 같은 몇 가지 사양을 추가 할 것입니다.

• W3C 권장 사항이며 JSON에서 상호 운용 가능한 웹 서비스를 빌드하는 방법을 지정하는 JSON-LD
• REST를위한 이온 하이퍼 미디어 유형 . " RES를 위한 단순하고 직관적 인 JSON 기반 하이퍼 미디어 유형"

제안 된 기본 프레임 워크는 잘 보이지만 정의 된 오류 객체는 너무 제한적입니다. 종종 하나의 값을 사용하여 문제를 표현할 수 없으며 대신 일련의 문제와 원인이 필요합니다 .

약간의 연구를 수행하여 오류 (예외)를 반환하는 가장 일반적인 형식은 다음 형식의 구조라는 것을 알았습니다.

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

이것은 OASIS 데이터 표준에서 제안한 형식입니다 OASIS OData 이며 가장 표준적인 옵션 인 것 같지만이 시점에서 표준의 채택률이 높지 않은 것 같습니다. 이 형식은 JSON-RPC 사양과 일치합니다.

이것을 구현하는 완전한 오픈 소스 라이브러리를 찾을 수 있습니다 : Mendocino JSON 유틸리티 . 이 라이브러리는 JSON 객체와 예외를 지원합니다.

자세한 내용은 JSON REST API의 오류 처리에 대한 내 블로그 게시물에서 설명 합니다.

상식 이외의 법률 위반 또는 무법 기준은 없습니다. 두 사람이 말하는 것처럼 이것을 추상화하면, 최소한의 단어로 최소한의 시간으로 정확하게 서로를 이해할 수있는 가장 좋은 방법은 표준입니다. 우리의 경우, '최소 단어'는 전송 효율을 위해 대역폭을 최적화하고 '정확하게 이해'는 파서 효율의 구조입니다. 궁극적으로 데이터가 적고 구조가 일반적입니다. 핀 구멍을 통과하고 공통 범위를 통해 구문 분석 할 수 있습니다 (최소한 초기에).

거의 모든 경우에 제안 된 것처럼 '성공'과 '오류'시나리오에 대한 별도의 응답을 볼 수 있습니다. 이 두 경우에 응답이 다르면 왜 거기에 '성공'플래그를 넣어야합니까? '오류'가없는 것이 '성공'이라는 것이 분명하지 않습니까? 'Error'가 설정된 'Success'가 TRUE 인 응답을 가질 수 있습니까? 또는 '성공'이 '오류'가 설정되지 않은 거짓입니까? 하나의 깃발만으로는 충분하지 않습니까? '성공'보다 '오류'가 적을 것이라고 생각하기 때문에 '오류'플래그 만 사용하는 것이 좋습니다.

또한 'Error'를 플래그로 만들어야합니까? 여러 검증 오류로 응답하려면 어떻게해야합니까? 따라서 각 오류가 해당 노드의 하위 인 '오류'노드를 갖는 것이 더 효율적입니다. 여기서 비어있는 (0으로 계산) '오류'노드는 '성공'을 나타냅니다.

모바일 개발자가 쉽게 이해할 수있는 웹 API에 대한 최상의 응답입니다.

"성공"응답입니다.

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

이것은 "오류"응답입니다

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}