RFC7807 RESTful API 실패에 대한 표준

GraphQL이 커지고 있지만, 아직 RESTful API가 많이 쓰이고, 이에 대한 표준 규격 OpenAPI 2.0 (구 Swagger)도 있다.

하지만, 여전히 RESTful API에 대한 정확한 이해없이 주먹구구식 API 설계를 하는 경우도 많고, 심지어 API First 가 아닌, 코드 구현한 다음 거꾸로 Swagger 파일을 만드는 경우도 있다. 마치 java 코딩을 다 한 후에, 역으로 comment를 달아 javadoc을 생성하는 것처럼 말이다.

HTTP Method인 GET, POST, PUT, DELETE에 대해서는 이해하고 쓰는 경우가 그래도 늘었지만, 응답값 특히 JSON 형식에 대해서는 Best Practice를 찾기가 힘들 정도다.

그런데 표준이 이미 있었다.

바로 RFC7807 rfc7807 (ietf.org)

표준을 보다보면 놀라운 점이 내가 고민하는 것들이, 이미 선구자들이 Best Practice를 만들어놨고, 그걸 표준화시켜놨다는 것이다.

200 OK 로 나오는 정상 응답값이 정상이니까, 서로 약속한 대로 받아 처리하면 되고, 실패에 대한 400시리즈, 500시리즈에서의 body를 어떻게 채울지를 가이드해주고 있다.

대표적인 client단의 요청에 대한 거절인 400인 경우, 아래처럼 하고..

{
    "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",
    "status": 400
}

403 Forbidden 도 아래처럼, 가이드를 하고 있다.

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

그리고, github과 npm으로 공개한 샘플 코드도 있다.

GitHub — PDMLab/http-problem: Create problem+json documents with Node.js

암튼, DRY에 충실하도록, 나보다 먼저 앞선 선구자의 Best Practice를 먼저 찾는 습관을 들여야겠다.