REST API 오류 반환 우수 사례

REST API 오류 반환 우수 사례 [닫힘]

---

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

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

그렇다면 업계 권장 사항은 무엇입니까? 모범 사례 (이유를 설명하십시오!) 그리고 클라이언트 관점에서 REST API의 어떤 종류의 오류 처리가 클라이언트 코드의 삶을 더 쉽게 만들어 주는가?

---

그래서 처음에는 200 OK와 특정 XML 페이로드 (예 : 더 많은 비용을 지불하면 필요한 스토리지를 얻을 수 있습니다!)와 함께 내 애플리케이션 오류를 반환하고 싶었지만 생각을 멈추고 비눗물처럼 보입니다 (/ 공포에 으쓱).

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

어떤 이유로 든 클라이언트의 스토리지 할당량이 초과 된 경우 403 (금지됨)을 반환합니다.

서버가 요청을 이해했지만 이행을 거부하고 있습니다. 승인은 도움이되지 않으며 요청은 반복되지 않아야합니다. 요청 방법이 HEAD가 아니고 서버가 요청이 수행되지 않은 이유를 공개하려는 경우 엔티티에서 거부 이유를 설명해야합니다 (SHOULD). 서버가이 정보를 클라이언트에 제공하지 않으려면 대신 상태 코드 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의 아이디어 중 하나는 API의 일부로 HTTP 상태 코드를 사용해야한다는 데 동의합니다 (성공적인 작업에는 200 또는 201을 반환하고 다양한 오류 사례에 따라 4xx 또는 5xx를 반환). 그러나 , REST 경찰이 없습니다. 당신이 원하는 것을 할 수 있습니다. 훨씬 더 심각한 non-REST API가 "RESTful"이라고 불리는 것을 보았습니다.

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

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

1. 오류 조건에 맞는 4xx 코드를 신중하게 선택해야합니다. 하위 코드 및 설명 주석을 포함하는 페이로드로 rest, 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는 피해야합니다.

---

나는 이것이 파티에 매우 늦었다는 것을 알고 있지만, 이제 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 ).

---

두 가지 종류의 오류가 있습니다. 애플리케이션 오류 및 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)

그러나 애플리케이션 오류를 설계하는 방법은 실제로 사용자에게 달려 있습니다. 예를 들어 Stack Overflow는 response, data및 message속성이 있는 개체를 보냅니다 . 내가 믿는 응답은 포함 true또는 false작업이 (일반적으로 쓰기 작업에 대한) 성공하면 나타냅니다. 데이터 (일반적으로 판독 동작에 대한) 페이로드를 포함하고, 메시지 (예를 들면 에러 메시지 등 추가적인 유용한 메타 데이터 또는 메시지를 포함 response이다 false).

---

동의합니다. 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를 피하십시오.

참고 URL : https://stackoverflow.com/questions/942951/rest-api-error-return-good-practices