예를 설명하겠습니다 :
제빵 소용 API를 만들기 시작합니다. 이 API를 사용하면 집에서 만든 민트 초콜릿 칩 쿠키와 같은 베이킹 제품에 대한 카탈로그를 검색 할 수 api.examplebakery.com/search?q=.....있습니다.
누군가 이것을 사용하여 명명 된 제품을 pineapple-banana flavoured cookies찾고 결과를 찾지 못할 것입니다.
이것이 오류로 반환되어야합니까? 검색이 실패하지 않았으며 API가 검색되었으며 쿠키를 찾을 수 없다는 결론을 내 렸습니다. 404API가 실제로 발견되었으므로 API가을 (를) 반환하지 않아야합니다 .
답변
결과가 있으면 출력은 (주석에 따라 JSON) 목록입니다. 결과가없는 쿼리의 경우 출력이 정확히 같아야합니다. 단순리스트에는 0 개의 항목이 있습니다.
따라서 귀하의 답변이 일반적으로 다음과 같은 경우 :
{
"results": [
{
"name": "Pancakes",
....
},
{
"name": "French Fries",
....
}
]
}
그런 다음 결과가 0 인 쿼리의 경우 다음과 같아야합니다.
{
"results": []
}
결과의 “페이지”수, 해당 “페이지”에 대한 링크 등에 대한 메타 데이터도 포함하는 경우 1 개의 “페이지”가 있다고 제안합니다.
HTTP 상태는 결과가있을 때와 같아야 200 OK합니다.
204 No Content또한 옵션으로 보이지만 실제로는 “콘텐츠”-빈 목록을 반환하기 때문이 아닙니다. 빈 목록이 “콘텐츠”로 계산되지 않는다고 생각되면 철자 제안을 제공하기 위해 응답을 수정하면 어떻게됩니까? 응답의 핵심은 여전히 빈 목록이지만 이제 더 많은 “콘텐츠”가 있습니다.
HTTP 상태 코드에 대한 더 유용한 정보는 jpmc26의 답변을 읽어보십시오.
답변
HTTP 코드를 결정할 때마다 항상이 질문을해야합니다.
임의의 클라이언트가 응답으로 무엇을 할 수 있습니까?
- 클라이언트가 항상 응답을 실패로 처리 해야합니까 ? 그런 다음 문제가 클라이언트의 입력인지 아니면 서버의 프로세스인지에 따라 4xx 또는 5xx를 원합니다.
- 클라이언트가 다른 곳에서 요청을해야합니까? 그렇다면 3xx는 당신을위한 것입니다.
- 서버가 클라이언트가 요청한 (성공한) 작업을 수행 했습니까? 2xx입니다.
항상 응답 코드의 범위를 먼저 결정하십시오. 그렇게하면 옵션으로 많은 응답 코드가 제거되며, 코드의 의미를 따르는 것이 훨씬 더 간단 해집니다. 각 코드 범주가 무엇을 나타내는 지에 대한 설명은 HTTP 코드 문서 의 시작 섹션을 참조하십시오 .
이 경우 클라이언트는 유효한 기존 엔드 포인트에서 필터를 제공 한 결과 목록을 요청했으며 액세스 권한이 있습니다. 서버가 요청을 처리하고 리턴 할 적절한 데이터 (항목 없음)를 판별 할 수 있었으므로 요청이 성공했습니다. 그들이 준 필터가 모든 결과를 걸러 낸 것 입니다. 이것이 일부 클라이언트에게는 예상되는 결과 일 수 있기 때문에 이것이 클라이언트가 원하는 것인지 아닌지를 결정하는 것은 서버에 달려 있지 않습니다. 클라이언트 코드에 문제가있는 경우, 클라이언트의 결정, 확인 및 처리는 클라이언트의 책임입니다. 따라서 이것은 분명히 2xx입니다.
이제 질문은 “2xx?”입니다. 이것은 서버의 응답 방식에 따라 다릅니다.
- 다른 답변이 설명하는 것처럼 빈 목록의 표현을 다시 보내 시겠습니까? 그렇다면 200을 원합니다. 200은 서버에 아무런 문제가 없으며 클라이언트가 소비 한 결과를 나타냅니다. 이것은 결과에 대한 여부에 대한 응답을 구문 분석 한 다음 빈 목록 자체를 처리하는 방법을 알아낼 수있는 가장 편리한 소비자 응답 방법입니다.
- 204는 의미 상 잘못된 것은 아니지만 메시지 본문없이 응답해야합니다 . 이것은 모든 클라이언트 코드가 다른 HTTP 코드를 명시 적으로 확인하거나 (또는 최소한 메시지 본문이없는 경우) 별도로 처리해야 함을 의미합니다. 불편하고 고객이 제대로 행동하지 않을 가능성이 높습니다.
다른 것들은 전혀 적용되지 않습니다 :
- 201은 의문의 여지가 없습니다. 영구 리소스를 만들지 않았으며 생성 된 리소스로 위치를 반환하지 않습니다.
- 202는 의문의 여지가 없습니다. 요청이 완료되었습니다. 백그라운드에서 처리되지 않습니다.
- 203은 권한이있는 서버와 클라이언트간에 응답이 수정되었음을 의미합니다. RESTful 인터페이스 는 신뢰할 수있는 서버이므로 여기에는 적용되지 않습니다.
- 205는 이해가되지 않습니다. 클라이언트가 아무것도 지우거나 새로 고칠 필요는 없습니다.
- 206은 여러 응답을 통해 큰 리소스를 반환하도록 설계되었습니다. 또한 클라이언트 가 헤더 의 컨텐츠 일부를 요청 해야합니다 (쿼리 문자열을 통한 페이지 매김은 적합하지 않음). 여기에는 해당되지 않습니다.
따라서 200 또는 204 여야하고 200은 더 단순하고 강력한 클라이언트 코드로 이어질 가능성이 높습니다 (특히 빈 목록이 포함 된 일관된 응답 구조를 사용하는 경우).
답변
아니요. 404를 사용하여 ‘조회가 처리되었지만 일치 항목이 없습니다’를 나타내는 것은 다음과 같은 이유로 끔찍합니다.
-
예외 처리를 기반으로하는 조건부 흐름 (예 : 예외적이지 않은 결과로 인해 클라이언트에서 예외적이지 않고 어색 할 수있는 예외를 만들고 처리하도록 함)
-
‘실제’페이지 사이의 모호함을 찾을 수 없습니다. 끝점을 잘못 입력했습니다. 오류
기억해야 할 것은 항상 메시지를 직렬화 해제하는 클라이언트와 해당 클라이언트가 리턴 한 내용이 중요하다는 것입니다. 직렬화가 아닙니다.
클라이언트가 널을 리턴해야하는 경우 널 직렬화를 사용하십시오. 클라이언트가 빈 배열을 반환해야하는 경우 []를 사용하고, 클라이언트가 500을 사용하고 오류 메시지를 전달해야하는 경우
답변
@Ewan의 매우 좋은 답변을 넘어서 :
쿼리가 결과 집합을 반환하는 종류 인 경우 빈 집합은 논리적으로 하나 이상의 집합만큼 적절합니다. @Ewan이 말한 이유 때문에 일반적으로 빈 세트를 오류로 변경하는 것이 좋은 것보다 더 해롭고 단순히 불필요합니다.
쿼리가 조회하고 특정 싱글 톤 (예 : id와 정확히 일치하는 것으로 예상 됨)을 반환하는 종류 인 경우 논리적으로 적절한 응답이 없습니다.
답변
데이터가 반환되지 않을 때 코드가 특별한 조치를 취해야한다고 가정하지만 그렇지 않을 수도 있습니다. 코드는 단순히 제품 수를 찾거나 결과를 목록이나 여러 가지로 추가 할 수 있습니다. 실제로 오류가있는 경우에만 사용자에게 “오류”를 제공해야합니다.
답변
API를 사용할 때 클라이언트는 “오류”사례와 다른 “성공”사례를 처리해야합니다. 나는 선택의 여지가 없다. 따라서 클라이언트 가 다르게 취급하고 싶을 때와 클라이언트 가 동일하게 취급하고 싶을 때 성공 하면 오류를 반환해야합니다 .
이론적으로 임의의 수의 결과, 0, 1, 2 백 등을 반환 할 수있는 쿼리를 수행하면 API가 모든 결과의 전체 목록을 제공 할 때마다 “성공”을 반환해야합니다. 결과가 많은 경우 과도한 크기를 피하기 위해 일부 결과 목록을 반환했으며 다른 결과를 얻는 방법에 대해 합의 된 방법이 있습니다. 클라이언트로서 종종 더 많은 결과와 같은 결과가없는 경우를 처리하기를 원하기 때문입니다. 나는 그것을 다르게 취급 할 수 있지만 강요하고 싶지 않습니다.
값을 찾는 경우와 다릅니다. 나는 정확히 하나의 결과, 내가 찾고있는 가치를 기대합니다. 그리고 의미있는 방식으로하고 싶은 일을 계속하려면 하나의 결과가 필요합니다. 어쨌든 다른 경우를 처리해야하기 때문에 값이없는 경우 상태 404를 반환하는 것이 훨씬 더 수용 가능합니다.
요약 : 클라이언트가 0에서 큰 숫자까지 많은 수의 결과를 예상하는 경우 숫자가 0 인 경우에도 모든 결과가 전달되면 “성공”을 반환합니다. 클라이언트가 정확히 하나의 결과를 기대하면 결과가 발견되면 성공을 반환하고 결과를 찾지 못하면 오류를 반환합니다.