Created: Updated:

오류 처리

많은 소프트웨어 개발자들은 나를 포함하여 예외 처리와 오류 처리를 생각하는 것을 좋아하지 않지만, 이는 모든 소프트웨어 개발자에게 중요한 부분입니다. 특히 API 디자이너에게 있어서 더욱 그렇습니다.

API 디자이너에게 좋은 오류 처리 디자인이 특히 중요한 이유는 무엇인가요?

웹 API를 사용하는 개발자의 관점에서 보면, 인터페이스 뒤에 있는 모든 것이 검은 상자입니다. 따라서 오류는 API를 사용하는 방법에 대한 문맥과 가시성을 제공하는 중요한 도구가 됩니다.

첫째로, 개발자들은 오류를 통해 코드 작성 방법을 익힙니다. XP(Extreme Programming) 모델의 “테스트 우선” 개념과 더 최근에 등장한 “테스트 주도 개발(Test-Driven Development)” 모델들은 개발자들이 일하는 중요하고 자연스러운 방식이기 때문에 발전된 모범 사례들의 집합입니다.

둘째로, 개발자들은 애플리케이션을 개발하는 과정에서 뿐만 아니라, API를 이용하여 만든 애플리케이션이 사용자들의 손에 넘어간 이후 문제를 해결하고 문제 해결을 위해 중요한 시기에는 잘 디자인된 오류 메시지에 의존합니다.

어떻게 REST에서 합리적인 방식으로 오류를 생각할 수 있을까요?

세 가지 주요 API가 어떻게 처리하는지 살펴보겠습니다.

Facebook

HTTP Status Code: 200

{
  "type" : "OauthException",
  "message":"(#803) Some of the aliases you requested do not exist: foo.bar"
}

Twilio

HTTP Status Code: 401

{
  "status" : "401",
  "message":"Authenticate",
  "code": 20003, 
  "more info": "http://www.twilio.com/docs/errors/20003"
}

SimpleGeo

HTTP Status Code: 401

{
  "code" : 401,
  "message": "Authentication Required"
}

Facebook Facebook에서는 어떤 요청이든 200 상태 코드를 받게 됩니다 - 모든 것이 잘 작동했다는 의미입니다. 많은 오류 메시지도 HTTP 응답으로 내려갑니다. 여기서도 #803 오류를 발생시키지만 #803이 무엇인지 또는 이에 대해 어떻게 대응해야 할지에 대한 정보는 제공하지 않습니다.

Twilio Twilio는 오류를 HTTP 상태 코드와 일치시키는 뛰어난 작업을 수행합니다. Facebook과 마찬가지로 더 세분화된 오류 메시지를 제공하지만 해당 링크를 통해 문서로 이동하도록 안내합니다. 문서에서 커뮤니티 댓글과 토론이 가능하여 이러한 오류를 겪는 개발자들에게 추가적인 정보와 맥락을 제공합니다.

SimpleGeo SimpleGeo는 오류 코드를 제공하지만 페이로드에 추가적인 값을 제공하지 않습니다.

몇 가지 모범 사례

HTTP 상태 코드 사용하기

HTTP 상태 코드를 사용하고 가능한 한 관련 표준 기반 코드와 깔끔하게 매핑하려고 노력해야 합니다.

HTTP 상태 코드는 70개가 넘습니다. 그러나 대부분의 개발자들이 이 모든 상태 코드를 기억하고 있지는 않습니다. 따라서 너무 흔하지 않은 상태 코드를 선택하면 애플리케이션 개발자들이 당신이 무엇을 말하려는지 이해하기 위해 앱을 만드는 대신 위키피디아로 가야 할 수 있습니다.

따라서 대부분의 API 제공업체는 작은 하위 집합을 사용합니다. 예를 들어, Google GData API는 10개의 상태 코드만 사용합니다. Netflix는 9개를 사용하며, Digg는 단 8개만 사용합니다.

Google GData

200 201 304 400 401 403 404 409 410 500

Netflix

200 201 304 400 401 403 404 412 500

Digg

200 400 401 403 404 410 500 503

API에서 얼마나 많은 상태 코드를 사용해야 할까요?

요약하면, 앱과 API 간 상호작용에는 실제로 세 가지 결과만 있습니다:

  • 모든 것이 정상 작동함 - 성공
  • 앱이 잘못된 요청을 보냄 - 클라이언트 오류
  • API가 잘못된 응답을 보냄 - 서버 오류

다음과 같은 3개의 코드부터 시작하세요. 더 필요하면 추가하세요. 하지만 8개 이상이 필요하지 않을 것입니다.

  • 200 - OK
  • 400 - Bad Request
  • 500 - Internal Server Error

만약 이 3가지로 모든 오류 조건을 충족시키기 어렵다면, 다음 5개 중 하나를 선택해보세요.

  • 201 - Created
  • 304 - Not Modified
  • 404 – Not Found
  • 401 - Unauthorized
  • 403 - Forbidden

(모든 HTTP 상태 코드에 대한 좋은 위키피디아 항목을 확인해보세요.)

반환된 코드가 애플리케이션의 비즈니스 로직에서 소비되고 처리될 수 있어야 합니다. 예를 들어, if-then-else 또는 case 문에서 처리할 수 있어야 합니다.

코드는 코드대로, 메시지는 사람이 이해할 수 있는 형태로 반환하는 것이 좋습니다.

코드 예시:

  • 200 – OK
  • 401 – Unauthorized
{
  "developerMessage" : "Verbose, plain language description of the problem for the app developer with hints about how to fix it.",
  "userMessage" : "Pass this message on to the app user if needed.",
  "errorCode" : 12345,
  "more info" : "http://dev.teachdogrest.com/errors/12345"
}

요약하자면, 가능한 한 상세하게 메시지를 작성하고 일반적인 언어로 표현해야 합니다. 발생한 오류에 대한 힌트를 최대한 많이 포함시키는 것이 좋습니다.

Twilio와 같이 자세한 정보를 제공하기 위해 설명에 링크를 추가하는 것을 강력히 추천합니다.

댓글남기기