[json] 표준 JSON API 응답 형식?

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!"
  }
}

답변

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

JSON API -JSON API는 응답뿐만 아니라 리소스 생성 및 업데이트도 포함합니다.
JSend- 단순하고 아마도 당신이 이미하고있는 것.
OData JSON 프로토콜 -매우 복잡합니다.
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 가지 유형이 있다고 생각합니다.

HTTP 상태 코드 만 사용 하여 오류가 있는지 표시하고 표준 오류로 제한하십시오 (보통 충분해야 함).
- 장점 : API와 독립적 인 표준입니다.
- 단점 : 실제로 일어난 일에 대한 정보가 적습니다.
HTTP Status + json body를 사용하십시오 (오류 인 경우에도). 오류 (예 : 코드, 메시지, 이유, 유형 등)에 대해 균일 한 구조를 정의하고 오류에 사용하십시오. 성공한 경우 예상 json 응답을 반환하십시오.
- 장점 : 기존 HTTP 상태 코드를 사용하고 오류를 설명하는 json을 반환 할 때 여전히 표준입니다 (발생한 상황에 대한 자세한 정보 제공).
- 단점 : 출력 json은 오류 또는 성공 여부에 따라 달라집니다.
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으로 상태 보고서를 캡슐화하는 것이 그보다 더 유용한 방법을 알 수 없습니다.