HTTP API는 항상 본문을 반환해야합니까?

HTTP API 응답에 관한 표준이 있습니까?

이 담화 실을 읽은 후 나는 궁금해하기 시작했다. 우리는 직장에서 공개 HTTP JSON API를 개발 중이며 엄격하게 필요하지 않은 경우 아무것도 반환하지 않습니다 (예 : PUT / resource / {id}는 OK 또는 해당 4XX 또는 5XX 코드 일 때 200 만 반환하지만 JSON 본문)

{"success":true}위의 링크에서 논의한 것처럼 일반적인 것을 반환해야합니까 , 아니면 "void"본문을 반환하고 http 응답 코드로 모든 것을 처리해도 괜찮습니까?

PUT과 관련하여 POST에도 적용됩니다. HTTP 사양 당신이 묘사하는 시나리오에 관해서 제 9 규칙 또는 조언 (SHOULD)에 약간 비어 있습니다. 귀하의 질문과 관련된 내용은 다음과 같습니다.

새로운 리소스가 생성되면 오리진 서버는 반드시 201 (Created) 응답을 통해 사용자 에이전트에게 알려야합니다. 기존 자원이 수정되면 요청 완료를 표시하기 위해 200 (OK) 또는 204 (No Content) 응답 코드를 보내야합니다.

나는 잠을 잃지 않을 것이라고 생각하지만, JSON 청크를 응답에 추가하면 무엇을 얻을 수 있습니까? 방금 상태 코드가 이미 말한 내용을 정확하게 반복하지 않는 응답을 벌크 아웃했습니다. PUT으로 인해 새로운 객체가 201을 반환하면 (PUT의 의도대로) 객체 반환을 업데이트하면 204가 반환됩니다.

또한 200을 대신하여 API를 제외하고 아무것도 반환하지 않으면 204를 사용하십시오.

RESTful 인터페이스 세트를 개발한다고 가정하면 표준 자체가 없기 때문에 무엇을 하든지 잘 문서화하고 예제를 제공하면 모든 것이 잘됩니다.

기본 HTTP 표준은 응답과 함께 반환 된 문서가 있어야한다는 것을 요구하지 않습니다. 경제를 위해, HTTP 상태가 필요한 모든 것을 전달할 때 신체는 낭비가됩니다. 그러나 새로운 규칙을 추가하는 HTTP 기반의 표준이 있습니다.

다음 을 지정 하는 공개 JSON API 표준 이 있습니다.

• JSON 객체 는 모든 JSON API 응답 문서 의 루트에 있어야 합니다 . (이탤릭체는 텍스트를 명확하게하기 위해 추가 한 것을 나타냅니다)

불행히도, 표준은 빈 문서를 표현하는 방법을 지정하지 않으며 진행중인 작업입니다. 기껏해야 가이드 라인으로 사용합니다.

ElasticSearch 와 같은 일부 응용 프로그램 은 전체 JSON API를 제공하며 항상 일부 메타 데이터가 있으므로 서버가 데이터를 관리하는 방법을 더 잘 이해할 수 있습니다. 표준 응답 객체는 인덱스의 상태, 요청으로 인해 오류가 발생한 경우, 영향을받은 노드 수 등을 알려줍니다. ElasticSearch는 MIME 유형에 "application / json"을 사용하므로 지침의 적용 가능성이 낮습니다. jsonapi.org 표준.

JQuery 및 유사한 Javascript 프레임 워크는 항상 문서가 있다고 가정합니다. 문제는 API 소비자에게 얼마나 많은 오류 검사를 하시겠습니까? 요청 유형을 기반으로 만 확장 된 모든 응답에 대한 표준 형식을 제시하면 반환 문서가 필요하고 API 소비자가 더 쉽게 디버깅 할 수 있습니다.

아니오 , 예를 들어, 204 개 응답을 우리는 메시지 본문을 포함하지 않아야합니다. {success | status | isSuccessful : true}는 중복입니다.

실제로 (또는 이후 버전의 jquery에서 말해야 함) 응용 프로그램 / json 내용 유형에 대한 빈 응답은 오류를 발생시킵니다. 나는 응용 프로그램 / json이기 때문에 유효한 json 본문이 있어야한다는 주장을 이해합니다. 따라서 application / json 컨텐츠 유형에 대한 빈 응답은 유효한 json 인 'null'또는 '{}'입니다.

jquery에서 작동 해야하는 또 다른 방법이 있습니다. 빈 응답에 대해 application / json을 반환하지 않습니다. 텍스트 / 일반 또는 무언가를 사용하고 클라이언트가 해당 유형을 처리 할 수 ​​있도록하십시오.

참고 메시지 본문 반환을 명시 적으로 금지 한 경우 204 만 기억할 수 있습니다. 우리가 발견 한 것은 항상 204를 사용할 수 없다는 것입니다. 문제는 204 응답에 대한 MSIE 드롭 응답 헤더이므로 컨텐츠 와 헤더 가 없기 때문에 좋지 않습니다. 많은 사람들이 MSIE를 사용하고 있으므로 200 상태로 변경해야했습니다.

아니요.하지만 코드 일관성을 유지하는 데 도움이됩니다. 디버깅 목적으로도 좋습니다. 또한 웹 사이트 유지 관리에 큰 도움이 될 것입니다. 이것을 기억하십시오 : 오류 코드는 기계 용이고 오류 메시지는 인간 용입니다. 따라서 응답 본문을 사용하는 것이 좋습니다. 어쨌든, 그 부정적인 효과는 장점과 비교하여 최소한 (네트워크를 통해 전송 된 몇 바이트)입니다. 또 다른 방법은 필요할 때 메시지 본문을 작성하는 것을 잊어 버리지 않도록합니다.

응답에서 단순히 성공 상태를 반환하지 않고 http 오류 코드는 성공 또는 오류를 나타냅니다. 응답 자체를 사용하여 응용 프로그램 별 오류 코드 또는 오류 메시지와 같은 자세한 오류 정보를 추가하는 것만 포함합니다.

PUT, PATCH 및 POST 요청의 경우 일반적으로 빈 응답이 아니라 요청이 적용된 후 상태가 리소스 상태를 반환합니다.

반환 할 유용한 데이터가없는 리소스 (매우 RESTful은 아니지만 실제로는 여전히 유용한)를 만드는 대신 작업을 나타내는 POST 요청의 경우 빈 json 객체로 구성된 응답을 반환합니다 (예 :) {}. 그렇게하면 클라이언트가 올바른 응답을 받고 나중에 정보를 추가해도 문제가 발생하지 않습니다.

DELETE 요청의 경우 204를 반환하면 빈 본문이 꽤 일반적입니다. 나중에 리소스가 존재하지 않기 때문에 의미가 있습니다.

필요한 것만 + 약간의 설명 만 반환하는 것이 좋습니다.

예를 들어, API 사용 방법에 따라 저장 후 존재하는대로 오브젝트 사본을 포함 할 수 있습니다.

따라서 {key : 123}의 POST는 {key : 123, foo : 'bar'}를 반환 할 수 있습니다.

기본 아이디어는 객체를 반환 한 다음 다시 쿼리해야하는 것이 좋습니다.

즉, API 소비자 중 객체를 필요로하지 않아도 반환 할 필요가 없습니다.

POST PUT 및 PATCH에 필요한 객체가 없으면 수신 측에서 쉽게 사용할 수 있기 때문에 일반적으로 {성공 : true} 또는 그와 같은 일부를 반환합니다. 즉, 객체의 저장된 표현을 반환하는 것이 시간의 99 %가 낫지 만, 어쨌든 필요하지 않은 경우는 거의 없으며, 한 번의 요청으로 두 번에 모두 보내는 것이 "저렴합니다".

구체적으로 말하자면 실험실에서는 상태 코드만으로 모든 것을 처리하는 것이 완벽하게 발견됩니다. 실제에서는 중복 된 경우에도 일부 데이터를 반환하는 것이 훨씬 낫습니다. 따라서 API 소비자는 사용자가 말하려는 내용을 쉽게 이해할 수 있습니다.

200을 반환하면 (성공 : true} 사람들이 두 가지 방식으로 코드를 작성할 수 있습니다.

if response.code == 200
  do stuff
end

과

if response.body.success
  do stuff
end

또한 당신 편으로는 그렇게 어렵지 않습니다.

마지막으로 (똥 답변 구조에 대해 유감스럽게도) 공개 JSON API를 제공하여 사용 방법에 대한 많은 제어권을 포기합니다. 일부 고객은 다른 기관 (또는 부재) 또는 상태 코드에 따라 다르게 반응 할 수 있습니다.