2024-06-28-TIL

2024-06-28-TIL

Today I Learned

ProblemDetail

• https://medium.com/@mandeepdhakal11/using-problemdetail-specification-for-error-response-in-spring-boot-3-5d25956ef421
• https://blog.restcase.com/rest-api-error-handling-problem-details-response/
• https://www.rfc-editor.org/rfc/rfc7807

Problem Details는 HTTP API의 오류 응답 형식을 표준으로 정한 IETF 문서다. 처음에는 RFC 7807이었고, 2023년 7월 RFC 9457이 나오면서 7807을 대체했다. 목적은 API마다 오류 응답 형식을 새로 만들지 않도록, 기계가 읽을 수 있는 공통 형식을 주는 것이다. 미디어 타입은 application/problem+json이다.

기본 필드는 다섯 개다.

• type : 문제 유형을 식별하는 URI. 클라이언트는 이 값을 문제 유형의 기본 식별자로 써야 한다.
• title : 문제 유형의 짧은 요약
• status : HTTP 상태 코드
• detail : 이번 발생 건에 대한 설명
• instance : 이번 발생 건을 가리키는 URI

RFC 9457에 실린 예시를 줄이면 다음과 같다. 403 응답의 본문이다.

{
  "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
}

balance는 표준 필드가 아니라 이 문제 유형이 정의한 확장 필드다. 이처럼 문제 유형에 맞는 필드를 더할 수 있다. RFC 9457에는 유효성 검사 오류 여러 개를 errors 배열로 담고, 각 항목에서 JSON Pointer로 문제 위치를 가리키는 예시도 있다.

Spring Framework는 6.0부터 이 형식을 직접 지원한다. ProblemDetail은 표준 필드와 확장 필드를 담는 객체이고, @ExceptionHandler나 컨트롤러 메서드에서 이것을 반환하면 RFC 9457 형식으로 응답한다. Spring MVC의 내장 예외는 모두 ErrorResponse를 구현하고 있어서, @ControllerAdvice에서 ResponseEntityExceptionHandler를 상속하면 프레임워크 예외까지 같은 형식으로 맞출 수 있다.

---

Standard API Response with JSON

• https://blog.lyunho.kim/api-response
• https://stackoverflow.com/questions/12806386/is-there-any-standard-for-json-api-response-format
• https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
• https://medium.com/@bojanmajed/standard-json-api-response-format-c6c1aabcaa6d

성공 응답까지 포함한 JSON 응답 형식에는 Problem Details 같은 단일 표준이 없다. 그래서 팀마다 { "success": ..., "data": ..., "error": ... } 같은 봉투(envelope)를 정해 쓰는 경우가 많다. 오류 쪽만이라도 Problem Details를 따르면, 봉투 형식을 따로 정하더라도 클라이언트가 오류를 다루는 방식은 표준에 기댈 수 있다.

---

AI 키워드: Claude 3.5 Sonnet

Anthropic이 6월 20일(미국 기준) Claude 3.5 모델군의 첫 모델인 Claude 3.5 Sonnet을 발표했다. 중간 등급 모델의 속도와 비용으로 이전 최상위 모델인 Claude 3 Opus를 여러 평가에서 앞서고, 속도는 Opus의 두 배라고 한다. 내부 에이전트 코딩 평가에서는 Opus가 38%를 푼 평가에서 64%를 풀었다고 밝혔다. 중간 크기 모델이 바로 이전 세대의 최상위 모델을 앞질렀다는 말이구나.

참고한 자료외부 출처 5

외부 출처

• RFC 9457: Problem Details for HTTP APIsIETF
• RFC 7807: Problem Details for HTTP APIsIETF
• ProblemDetail.java (v6.0.0) - Spring FrameworkGitHub
• Error ResponsesSpring Framework Reference
• Claude 3.5 SonnetAnthropic