[Spring] RESTful API 컨벤션

1. API URI는 동사를 사용하지 않는 것이 권장된다.

GET/POST/PUT/DELETE/PATCH 등 메소드에 이미 조회, 생성 등의 의미를 포함하고 있기 때문에 API URI에 동사는 제외하는 것이 좋다.

1) 아쉬운 예시

@GetMapping("/getItemInfo")
public Response getItemInfo(final Request request) {
	...
}

2) 권장 예시

@GetMapping("/itemInfo")
public Response getItemInfo(final Request request) {
	...
}

2. API Return 값에는 Error/Success 메세지, 코드 등을 포함하면 좋다.

API를 사용하는 클라이언트 입장에서 Error/Success 메세지, 코드를 받는다면 구현이 편하다!

@GetMapping("/itemInfo")
public Response getItemInfo(final Request request) {
	...
    
    // 성공 시
    if (success) {
    	return Response.builder()
    		.result(result)
        	.resultCode("10")
        	.resultMessage("조회에 성공하였습니다.")
        	.resultDescription("성공!")
        	.build();
    }
    
    // 실패 시
    return Response.builder()
        .resultCode("99")
        .resultMessage("조회에 실패하였습니다.")
        .resultDescription("실패!")
        .build();
}

• 위와 같이 API 작성 시, API 스펙 명세는 필수적이다.

참고

https://abdulrwahab.medium.com/api-architecture-best-practices-for-designing-rest-apis-bf907025f5f