REST API 오류 리턴 우수 사례 [닫기]

REST API에서 오류를 반환 할 때 모범 사례에 대한 지침을 찾고 있습니다. 새 API를 개발 중이므로 지금 어떤 방향 으로든 사용할 수 있습니다. 내 콘텐츠 유형은 현재 XML이지만 향후 JSON을 지원할 계획입니다.

예를 들어 클라이언트가 새 리소스를 추가하려고하지만 스토리지 할당량을 초과 한 경우와 같은 일부 오류 사례를 추가하고 있습니다. HTTP 상태 코드 (인증의 경우 401, 권한 부여의 경우 403, 일반 잘못된 요청 URI의 경우 404)의 특정 오류 사례를 이미 처리하고 있습니다. 나는 축복받은 HTTP 오류 코드를 살펴 보았지만 400-417 범위 중 어느 것도 응용 프로그램 특정 오류를보고하는 것으로 보이지 않습니다. 그래서 처음에는 200 OK와 특정 XML 페이로드 (예 : 우리에게 더 많은 돈을 지불하면 필요한 저장 공간을 얻을 수 있습니다!)로 응용 프로그램 오류를 반환하려고 시도했지만 생각을 멈추고 비눗물처럼 보입니다 (/ 공포에 으)). 게다가 오류 응답을 별개의 경우로 나누는 것처럼 느껴집니다. 일부는 http 상태 코드로 구동되고 다른 것은 컨텐츠 기반입니다.

그렇다면 업계 권장 사항은 무엇입니까? 모범 사례 (이유를 설명하십시오!)와 클라이언트 POV의 REST API에서 어떤 종류의 오류 처리를 통해 클라이언트 코드를보다 쉽게 ​​사용할 수 있습니까?

그래서 처음에는 200 OK와 특정 XML 페이로드 (예 : 우리에게 더 많은 돈을 지불하면 필요한 스토리지를 얻을 수 있습니다!)로 응용 프로그램 오류를 반환하려는 유혹을 받았지만 생각을 멈추고 비눗물처럼 보입니다 (/ 공포에서 어깨를 으)).

요청에 아무런 문제가 없으면 200을 반환하지 않습니다. 에서 RFC2616 , 200 개 수단 "요청이 성공했습니다."

어떤 이유로 든 클라이언트의 저장 용량이 초과 된 경우 403 (금지됨)을 반환합니다.

서버가 요청을 이해했지만 요청 이행을 거부하고 있습니다. 승인은 도움이되지 않으며 요청을 반복해서는 안됩니다. 요청 방법이 HEAD가 아니고 서버가 요청이 이행되지 않은 이유를 공개하기를 원한다면, 엔티티에서 거부 이유를 설명해야한다. 서버가이 정보를 클라이언트가 사용할 수 없게하려면 상태 코드 404 (찾을 수 없음)를 대신 사용할 수 있습니다.

이것은 클라이언트에게 요청은 정상이지만 실패했다는 것을 알려줍니다 (200은하지 않는 것). 또한 응답 본문에서 문제 (및 해결 방법)를 설명 할 수있는 기회를 제공합니다.

다른 특정 오류 조건을 염두에 두셨습니까?

API에 맞는 HTTP 오류 코드를 선택하는 데 도움이되는 유용한 리소스 : http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

기사에서 발췌 :

어디서 시작하나요:

2XX / 3XX :

4XX :

5XX :

주요 선택 사항은 HTTP 상태 코드를 REST API의 일부로 처리할지 여부입니다.

두 가지 방법 모두 잘 작동합니다. 엄밀히 말하면 REST의 아이디어 중 하나는 HTTP 상태 코드를 API의 일부로 사용해야한다는 것입니다 (성공적인 작업을 위해서는 200 또는 201을 반환하고 다양한 오류 사례에 따라 4xx 또는 5xx를 반환하십시오). REST 경찰은 없습니다. 당신이 원하는 것을 할 수 있습니다. 나는 훨씬 더 비 심각한 비 REST API가 "RESTful"이라고 불렀습니다.

이 시점에서 (2015 년 8 월) API의 일부로 HTTP 상태 코드를 사용하는 것이 좋습니다. 프레임 워크를 사용할 때 과거보다 리턴 코드를 보는 것이 훨씬 쉽습니다. 특히 200이 아닌 리턴 사례와 200이 아닌 응답 본문을 과거보다 더 쉽게 확인할 수 있습니다.

HTTP 상태 코드는 API의 일부입니다

1. 오류 조건에 맞는 4xx 코드를 신중하게 선택해야합니다. 하위 코드 및 설명 주석이 포함 된 페이로드로 나머지, xml 또는 일반 텍스트 메시지를 포함 할 수 있습니다.

2. 클라이언트는 HTTP 레벨 상태 코드를 얻을 수있는 소프트웨어 프레임 워크를 사용해야합니다. 일반적으로 가능하지만 항상 간단한 것은 아닙니다.

3. 클라이언트는 통신 오류를 나타내는 HTTP 상태 코드와 응용 프로그램 수준 문제를 나타내는 자체 상태 코드를 구분해야합니다.

HTTP 상태 코드는 API의 일부가 아닙니다

1. 앱이 요청을 수신 한 후 응답 한 경우 (성공 및 오류 사례 모두) HTTP 상태 코드는 항상 200입니다.

2. 모든 답변에는 "봉투"또는 "헤더"정보가 포함되어야합니다. 일반적으로 다음과 같습니다.

   envelope_ver : 1.0
   상태 : # 원하는 코드를 사용하십시오. 성공을위한 코드를 예약하십시오.
   msg : "ok"# 코드를 반영하는 인간 문자열. 디버깅에 유용합니다.
   data : ... # 응답의 데이터입니다 (있는 경우).

3. 응답 상태는 항상 동일한 위치 (하위 코드 필요 없음), 코드 제한 없음, HTTP 수준 상태 코드 가져 오기 필요 없음으로 인해이 방법이 더 쉬울 수 있습니다.

비슷한 생각을 가진 게시물이 있습니다 : http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

주요 이슈:

1. 필요한 경우 나중에 API의 의미를 변경할 수 있도록 버전 번호를 포함하십시오.

2. 문서...

HTTP / 1.1 RFC에 정의 된 것보다 많은 상태 코드가 있음을 기억 하십시오 . IANA 레지스트리는 http://www.iana.org/assignments/http-status-codes에 있습니다. 당신이 상태 코드 507을 언급 한 경우에는 소리가납니다.

다른 사람들이 지적했듯이 오류 코드에 응답 엔터티를 갖는 것은 완벽하게 허용됩니다.

5xx 오류는 서버 측이므로, 클라이언트는 요청을 전달하기 위해 요청으로 아무것도 변경할 수 없습니다. 클라이언트의 할당량을 초과하면 서버 오류가 아닌 것이므로 5xx를 피해야합니다.

두 가지 종류의 오류가 있습니다. 응용 프로그램 오류 및 HTTP 오류 HTTP 오류는 AJAX 핸들러에 문제가 발생했음을 알리고 다른 용도로는 사용해서는 안된다는 것입니다.

5xx 서버 오류

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx 성공

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

그러나 응용 프로그램 오류를 디자인하는 방법은 전적으로 귀하에게 달려 있습니다. 스택 오버플로는 예를 들어와 객체 발송 response, data및 message특성을. 내가 믿는 응답은 포함 true또는 false작업이 (일반적으로 쓰기 작업에 대한) 성공하면 나타냅니다. 데이터 (일반적으로 판독 동작에 대한) 페이로드를 포함하고, 메시지 (예를 들면 에러 메시지 등 추가적인 유용한 메타 데이터 또는 메시지를 포함 response이다 false).

나는 이것이 파티에 매우 늦다는 것을 알고 있지만, 이제는 2013 년에 일반적인 분산 (RESTful) 방식으로 오류 처리를 다루는 몇 가지 미디어 유형이 있습니다. "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) 및 "HTTP API에 대한 문제점 세부 사항", application / problem + json ( https : // tools)을 참조하십시오. ietf.org/html/draft-nottingham-http-problem-05 ).

동의했다. REST의 기본 철학은 웹 인프라를 사용하는 것입니다. HTTP 상태 코드는 HTTP 페이로드를 늘리지 않고도 당사자들이 서로 통신 할 수있는 메시징 프레임 워크입니다. 이들은 이미 응답 상태를 전달하는 범용 코드로 설정되어 있으므로 진정으로 RESTful하려면 애플리케이션이이 프레임 워크를 사용하여 응답 상태를 통신해야합니다.

HTTP 200 엔벨로프에서 오류 응답을 보내는 것은 오해의 소지가 있으며, 클라이언트 (api 소비자)가 메시지를 비표준 또는 독점적 인 방식으로 구문 분석하도록합니다. 이는 또한 비효율적입니다. 클라이언트는 "실제"응답 상태를 이해하기 위해 매번 HTTP 페이로드를 구문 분석해야합니다. 이는 처리를 증가시키고 대기 시간을 추가하며 클라이언트가 실수 할 수있는 환경을 만듭니다.

기존의 '모범 사례'에서 API를 모델링하는 것이 좋습니다. 예를 들어, Twitter가 오류 코드를 처리하는 방법은 다음과 같습니다. https://developer.twitter.com/en/docs/basics/response-codes

프로토콜의 의미를 고수하십시오. 성공적인 응답에는 2xx를 사용하고 오류 응답에는 4xx, 5xx를 사용하십시오 (비즈니스 예외 또는 기타). 프로토콜에 의도 된 유스 케이스 인 응답에 2xx를 사용했으면 처음에는 다른 상태 코드가 없습니다.

응용 프로그램 오류뿐만 아니라 5xx 오류도 잊지 마십시오.

이 경우 409 (충돌)는 어떻습니까? 이것은 저장된 자원을 삭제하여 사용자가 문제점을 해결할 수 있다고 가정합니다.

그렇지 않으면 507 (완전히 표준은 아님)도 작동 할 수 있습니다. 일반적인 오류에 200을 사용하지 않으면 200을 사용하지 않습니다.

클라이언트 할당량을 초과하면 서버 오류이므로이 경우 5xx를 피하십시오.