RFC 문서

RFC란 Request For Comments의 약자로 의견 요청이라는 뜻이 담겨져있다.

위키에 따르면.

인터넷 기술에 적용 가능한 새로운 연구 , 혁신 , 기법등을 아우르는 메모를 의미한다.

 

인터넷 협회에서 기술자, 컴퓨터 과학자들이 RFC메모 형태로 의견을 제출해서, 또 다른 전문가의 비평을 받거나 생각을 전달한다.또한 인터넷 국제표준화 기구(IETF)는 일부 RFC를 인터넷 표준으로 받아들이기도 한다.

https://www.rfc-editor.org/standards 여기를 확인하면 표준으로 채택된 RFC문서가 무엇이 있는지 확인할 수 있다.

 

Document Retrieval » RFC Editor (rfc-editor.org) 이곳에서 RFC문서들을 확인할 수 있는데, 

우리가 사용하는 어플리케이션, 인터넷, 보안등등 프로토콜의 문서를 확인 할 수 있다.

 

RFC문서가 워낙 많기 때문에 다 볼 수는 없고, 시니어개발자님이 보여주신 RFC7807를 한번 살펴보려고한다.

사실 이 문서를 보는 이유는 API 송신시 에러를 얼마나 구체적으로 보내주어야 좋은 걸까? 의 취지에서 시작하였다. 

 

---

RFC-7807 : Problem Details for HTTP APIs

해당 문서는 "problem detail"을 정의하는데, 이는 기계가 읽기위해서

Http응답중 에러를 회피하기 위해, 새로운 Http API의 에러 형식을 정의하기위해 작성되었다.

또, IETF의 공개검토를 받았고 출판 승인도 받았다.

 

이제부터 내용을 살펴보자.

 

1. 소개 

Http Status만으로 에러에 대한 충분한 정보 제공이 되지 않다는 것을 문제 삼고,

Http Respons Body에 정보 제공을 할 수 있다고 말한다.

 

여기서 제안하는 방식은 JSON, XML을 사용하는 방법이고, 이는 Http APs를 사용함으로써

클라이언트가 조금 더 오류에 대해 세밀한 정보를 알 수있다고 말한다.

 

예를들어, 403 Forbidden 상태코드의 경우 접근 허용을 금지하는 상태 코드인데,

왜 허용이 금지되었는지 클라이언트에게 전달이 되지 않는다고 지적한다.

 

만약 여기서 제안하는 규격을 사용한다면 사용자에게 "권한 부족" 이라던가, 

"권한이 없어진지 일주일이 지났습니다." 라던가 조금 더 구체적인 오류를 제공할 수 있다.

 

물론 이 방법이 유일한 방법은 아니고 여러 방법들이 있지만,

공툥 오류 형식을 정의하여 자체적으로 정의할 필요가 없도록 하는게 의의이다.

 

2.이 문서를 읽기전에..

"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 의 용어가 나오는데, 이는 RFC2119를 확인하여 파악해야 한다.

해당 용어에 대한 설명은 

RFC 2119 한국어 번역본 (techhtml.github.io)

에 상세히 나와 있으며, 

표로 만들어 보자면

 

용어	설명
MUST, REQUIRED, SHALL	절대적인 요구사항, 반드시 준수
MUST NOT, SHALL NOT	절대해서는 안되는 금지사항
SHOULD, RECOMMENDED	권장사항이며, 해당 사항과 다른 방향으로 가려면 신중한 판단 필요
SHOULD NOT, NOT RECOMMENDED	권장하지 않으며, 역시 이를 진행하려면 신중한 판단 필요
MAY, OPTIONAL	옵션적인 요소, 부가적인 요소로만 작동  옵션이 없는 경우와 비교해서 상호작용을 할 수 있어야한다.

 

 

3. Problem Details Json Object

1) 예시

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

   {
    "type": "https://example.com/probs/out-of-credit",
    "title": "당신의 credit이 부족합니다.",
    "detail": "현재 잔액은 30원이지만, 필요Credit은 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": "요청한 파라미터가 유효하지 않습니다.",
   "invalid-params": [ {
                         "name": "age",
                         "reason": "나이는 숫자로 입력해야 합니다."
                       },
                       {
                         "name": "color",
                         "reason": "색깔은 red, green, blue이여야 합니다."}
                     ]
   }

 

 

2) 변수 설명

 

"type": 해당 문제 유형에 대한 참조 URI이다. 문제원인에 대한 사람이 읽을 수 있는 문서 제공에 쓰인다.

            제공되지 않는 경우 "about:blank"로 기본값으로둔다. (HTML 문서로 읽을수 있게 하는 것을 권장)
            - 소비자는 "type"을 문제유형 주요 식별자로 사용해야한다.

"title": 사람이 읽을 수 있는 짧은 오류 메시지, 

           - "type"에 "about:blank"를 사용하는 경우, "title"은 해당 코드에 대한 권장 HTTP 상태 구문과 같아야 한다.

"status": 필요한 경우 HttpStatus Code를 사용한다.
              - 일반적인 Http 소프트웨어에서 잘 작동하기 위해 기존 HttpStatus Code로 사용해야한다.

"detail": 사람이 읽을 수 있는 오류에 대한 더 명확한 설명 
              - 클라이언트가 문제를 해결하기 위한 도움을 주는데 집중해야한다.
              -  소비자는 해당 내용을 한번더 변환하지 않는 것을 권장한다. (혼동 생기기 때문)

"instance" : 문제의 발생을 식별하는 참조 URI

 

3) 변수 확장 

예를들어 위에서 크레딧이 부족하다고 경고를 띄웠지만, 

"acount", "balance"를 표기해서 조금 더 사용자에게 정보를 제공 할 수 있다.

단, 클라이언트측에서 인식하지 못하는 확장 변수는 무시할 수 있다. (보내주지만 필요없는 변수의 경우)

 

4.새로운 문제 유형 정의시에는

• 보안에 위배되는 사항이 없는지 확인 (가장 중요)
• 추가 되었을 때 좋은 효과가 있는지 확인
• IE와 같은 경우 일반적인 status code로 사용하여 처리하는것이 낫다. (현재는 종료)
• 알파벳 문자, 숫자, "_"를 사용하며 3자이상으로 권장한다.
• 정의시에 필요한 내용
  - type URI
  - 적정한 묘사가 담긴 title
  - Http Status

 

5.보안

• 시스템정보 , 시스템 사용자 개인정보 유출에 유의한다.
• 스택 덤프와 같은 세부 정보를 제공하지 않는다. (서버 구성)
• "status"를 넣는경우 Http status 코드와 중첩되나, 중개자에 따라 상태코드가 수정될 수 있으므로 유의한다.
  (이에 따라 사용자가 상태코드를 잘모르거나 의존할 가능성이 낮을 수도 있어진다.)

 

 

---

 

이렇게 해서 RFC 7807에 대한 문서를 읽어 보았다.

평소에 에러메시지, 에러코드, 에러객체 등에 대한 고민이 있었는데,

나와 비슷한 고민을 가졌었던, 전문가들의 의견을 보고 고민이 줄어드는 것 같아 재밌었다.