RESTful API Design: what about errors? | Apigee Blog

RESTful API Design: what about errors? | Apigee Blog:

왜 에러디자인이 중요한가? 

• API를 직관적으로 보이게 하고, 개발자를 도와준다. 
• 에러라는 것은 그 API를 어떻게 써야 하는지에 대한 이해를 돕는다. 
• 개발자는 잘 디자인된 에러들에 의존한다.

REST 에서의 에러에 대한 실용적인 방법은 무엇인가?

(다음의 예시들을 보자.)

Facebook 

• 에러메시지를 HTTP Response 에 밀어넣었다. 
• #803 이라는 에러가 있지만, #803에 대해서 어떻게 반응해야하는지가 없다. 

Twilio

• Response 에 HTTP Status 코드 뿐만 아니라 메시지와 관련 문서가 있는 정보 까지 넣었다. 

SimpleGeo

• 에러 코드들을 제공하는데 추가적인 정보는  없다. 

A couple of best practices

Use HTTP Status Codes 

HTTP 상태 코드를 사용하고 상태코드들을 표준코드와 연관시켜라.

70 여가지의 HTTP 상태코드가 있지만, 대부분의 개발자들은

70개를 다 기억하지 못한다. 그래서 많이 사용하지 않는 HTTP STATUS 코드를 선택하고 어플리케이션 개발자에게 사용하게 하고 이해시켜라. 

대부분의 API 제공업체들은 작은 서브셋을 사용한다. 예를들어 구글 GData API 는 10개의 상태코드를, Netflix 는 9개를 사용한다. 

How many status codes should you use for your API?

application 과 api 사이에서의 상호작용에서 3가지의 결과가 있다. 

• 모든게 잘 작동되는것
• application 쪽에서 문제 
• API 쪽에서의 문제 

기본적으로 3가지 코드는 기본이고 필요하다면 더 넣으면 되는데 8개가 넘지는 말아야 한다. 

• 200 – ok
• 404 – not found
• 500 – internal error 

3개만 하는게 너무 적다고 생각되면 추가 5개를 더 한다. 

• 201 – Created
• 304 – Not Modified
• 400 – Bad Request
• 401 – Unauthorized
• 403 – Forbidden

중요한 것은 이 코드들이 반환되어서 application의 비지니스 로직상에서 작동한다는 것이다. 

Make messages returned in the payload as verbose as possible

(가능한한 반환되는 payload 에 메시지를 만들어라)

• 메시지를 많이 쓰고. 
• 명료하게 서술하고.
• 무엇이 에러를 일으키는지에 대해서 많은 힌트를 줘라.
• 추가적인 정보를 위해서 링크를 제공하는 것을 추천한다. 

ps. 번역 하면서 빠진 부분도 있습니다. 원본을 보시는것도 좋습니다.