2021-05-19-TIL

2021-05-19-TIL

RESTful API naming

• https://www.ecma-international.org/publications-and-standards/standards/ecma-404/
• https://devuna.tistory.com/79
• https://sanghaklee.tistory.com/57

첫 번째 링크는 JSON 문법을 정의한 ECMA-404 표준이다. JSON을 언어에 독립적인 텍스트 기반 데이터 교환 문법으로 정의하고, 의미 해석은 각 애플리케이션에 맡긴다. 그래서 필드 이름을 camelCase로 할지 snake_case로 할지는 표준이 아니라 API를 만드는 쪽의 약속이다. 한 API 안에서는 한 가지로 통일해야 한다.

URI 이름을 지을 때 기본이 되는 생각은 “URI는 자원을, HTTP 메서드는 행위를 나타낸다”는 것이다. RFC 7231은 GET을 현재 표현을 가져오는 것, PUT을 자원의 상태를 바꾸는 것, DELETE를 자원을 지우는 것으로 정의한다. 그래서 동사는 URI 대신 메서드에 둔다.

피할 형태	권장 형태
GET /getRooms	GET /rooms
POST /rooms/create	POST /rooms
POST /rooms/3/delete	DELETE /rooms/3

그 밖에 REST API 이름에 흔히 쓰는 관례는 다음과 같다.

• 컬렉션은 복수 명사로 쓴다(/rooms, /rooms/3).
• 계층 관계는 경로로 표현한다(/rooms/3/reservations).
• 단어 구분은 하이픈(-)을 쓰고 대문자와 밑줄은 피한다.
• 필터, 정렬, 페이지는 경로가 아니라 쿼리 파라미터로 둔다(/rooms?location=서울).

---

How to return different HTTP Status Codes in Spring Boot Rest Controller?

• https://stackoverflow.com/questions/24292373/spring-boot-rest-controller-how-to-return-different-http-status-codes

상태 코드는 첫 자리로 의미가 나뉜다. 2xx는 성공, 3xx는 추가 동작 필요, 4xx는 클라이언트 오류, 5xx는 서버 오류다(RFC 7231 6장). 같은 컨트롤러 메서드에서 상황에 따라 다른 코드를 돌려주려면 ResponseEntity를 반환한다(Spring Javadoc).

@PostMapping("/rooms")
public ResponseEntity<RoomDto> create(@RequestBody RoomRequest request) {
    RoomDto room = roomService.create(request);
    return ResponseEntity.created(URI.create("/rooms/" + room.getId())).body(room);
}

@GetMapping("/rooms/{id}")
public ResponseEntity<RoomDto> find(@PathVariable Long id) {
    return roomService.find(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
}

created는 201과 함께 Location 헤더를 채우고, notFound는 404를 만든다. 항상 같은 코드를 돌려준다면 메서드에 @ResponseStatus(HttpStatus.CREATED)를 붙이는 것으로 충분하다. 예외 상황마다 코드가 달라지면 @ExceptionHandler에서 ResponseEntity를 만드는 방식이 깔끔하다.

현재 RFC 7231은 RFC 9110으로 대체되었지만 메서드와 상태 코드의 의미는 그대로다.

참고한 자료외부 출처 3

외부 출처

• ECMA-404 The JSON data interchange syntaxecma-international.org
• RFC 7231 HTTP/1.1 Semantics and ContentIETF
• ResponseEntitySpring Framework Javadoc