HTTP API 에러 쓰는 법

snowmerak included in Information

2024-05-21 439 words 3 minutes

Contents

왜?

HTTP API에 에러 쓰는 건 개인 취향 혹은 조직에서 정한 룰 아닌가요?

저도 그렇게 생각하고 있습니다.
모름지기 학사 과정을 수료했든, 학원을 수료했든, 부트캠프를 수료했든, 백엔드 개발자라면 알아서 잘 남길 수 있을 것입니다.

그럼 왜 이 글이 있는 거죠?

RFC에 HTTP API의 에러에 관한 내용이 있더라구요. 흥미로워서 가져왔습니다.

RFC7807

RFC7807은 Problem Details for HTTP APIs라는 이름의 문서입니다.
이름 그대로 HTTP API에서 발생하는 오류 응답 형식을 적어놓은 문서죠.

이 문서에서는 application/problem+json MIME 타입을 소개합니다.

application/problem+json

이 이상한 타입의 json에 대해 RFC7807에서는 아래와같은 예제를 몇가지 던져줍니다.

        
        
        
    
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

        
        
        
    
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
                      "name": "age",
                      "reason": "must be a positive integer"
                    },
                    {
                      "name": "color",
                      "reason": "must be 'green', 'red' or 'blue'"}
                  ]
}

대략적으로 이런 형태를 가집니다.
규칙성이 보이는 부분은 type과 title이 필수라는 점과 딱 봐도 도메인 특화된 필드를 추가로 넣을 수 있다는 게 있을 것입니다.
아래 파트에서 조금만 자세히 확인해보겠습니다.

필드에 대해

type: 문자열 타입으로 이 필드는 해당 에러에 대해 더 자세한 정보를 확인할 수 있는 URL입니다. 만약 여러분들이 Azure Cosmos DB의 서비스 페이지를 개발하고 있다면, 해당 페이지를 type으로 쓸 수 있을 것입니다. 이 필드는 필수값입니다. 부가적으로 이 필드의 링크는 html 형식이길 권장합니다.
title: 문자열 타입으로 이 필드는 문자 그대로 해당 문제에 대한 타이틀입니다. 필수 항목이며, 동일한 문제에는 동일한 타이틀이 제공되어야 합니다. 그리고 사람이 읽을 수 있는 형식으로 제공되어야 합니다.
status: 정수 타입으로 origin 서버로부터 받거나, 현재 서버에서 발생한 HTTP 상태 코드입니다. 선택 사항입니다.
detail: 이 문제에 대해 사람이 읽을 수 있는 상세한 내용입니다. 선택 사항입니다.
instance: 이 문제가 발생한 URI입니다. 선택 사항이며, /api/auth/login처럼 작성합니다.

그리고 추가적인 정보를 전달하기 위해 Extension Members(확장 멤버)를 제공합니다.
이 부분이 아까 예시에 있었던, balance나 accounts, invalid-params에 해당합니다.

확장 멤버는 본인이 필요한 케이스가 아닐 경우, 읽지 않아야 합니다.
이를 통해 오류 응답 형식을 확장하여 더 많은 필드를 쓸 수 있게 해줍니다.

주의 사항

오류 응답 형식을 사용할 때 다음 사항에 대해 주의를 당부합니다.

디버깅을 위한 도구가 되어선 안됩니다.
일반적인 HTTP 상태 코드를 통한 표현을 우선시 해야합니다.

오류 응답 형식 확장

새로운 오류 응답 형식을 생성할 때는 다음 사안을 고려합니다.

새로운 오류에 대한 적절한 type 값
새로운 오류에 붙일 수 있는 고유한 title
새로운 오류에 어울리는 status 코드

부가적으로 상세 정보(detail), 발생한 URI(instance), 확장 멤버(Extension Members)를 추가할 수 있습니다.
새로운 오류 응답 형식이 만들어지면, 적절한 DTO로 확장 및 공유하여 사용합니다.

네이밍 및 값에 대한 형식과 제한은 json의 그것을 따릅니다.
문서 자체에서는 영문자, 숫자, 언더바(_)만 사용하기를 권장합니다.

이번에도 당연히

RFC7807을 읽으며, 필요한 사용법을 위해 직접 라이브러리를 만들었습니다.

snowmerak/httperror