20231220 TIL

API 설계하기

1. 대원칙

중요한 것은 리소스를 잘 구분해 주는 것이다.
리소스는 동사가 아니다. 잘 쪼갠 명사임
회원가입이라는 단어를 보면, 얼핏 보면 명사처럼 보이지만
회원을+가입하다 로 나눌 수 있다.
여기서 리소스는 회원이고, 가입하다는 리소스의 행동이라고 이해하면 될 것 같다.
한글로 된 표현을 영어로 바꿔보면, 무엇이 명사이고 무엇이 행동인지 더 파악하기 쉬운 것 같다.
그렇다면 여기서는 '회원'이라는 리소스만 식별해서 URI에 매핑해주면 됨

2. API 설계 가이드

1. 리소스의 이름 : 명사, 소문자, 복수형을 사용
2. 계층 표현하기
   '/' 를 쓰면 된다. 폴더 경로 적는것 처럼 표현한다.
   다만 폴더 경로를 입력할 때도 들어가려는 폴더의 끝에는 '/'를 붙히지 않는 것처럼, API 설계할 때도 똑같이 하면 됨
3. 가독성을 높히고 싶을 때 구분자는 '-'를 쓰고 , '_' 는 쓰지 않는다.

3. POST에 관해

POST 메소드의 정의는 다음과 같이 되어있다.

The POST method requests that the target resource process the
representation enclosed in the request according to the resource's
own specific semantics.

이걸 좀 풀어서 해석해 보자.

POST Method는 요청합니다. / 대상 리소스의 프로세스/표현/요청에 포함되어 있는/리소스의 고유한 내용에 따라

조금 더 한글스럽게 바꿔보자.

POST Method는 요청합니다. / 대상 리소스 처리 방법을/ 그런데 그 처리 방법이 요청에 포함되어 있는 /리소스의 고유한 내용에 따라

이래도 조금 해석이 어색한 느낌은 있지만, 어쨌든 중요한 것은 리소스마다 처리 방법이 다르며 그 처리 방법을 요청이 올때마다 따로 정해야 한다는 것
따로 정해야 한다는 것을 바꿔 말하면, 원하는 모든 것을 다 할 수 있다는 이야기도 된다. 뭔가 애매하다 싶으면 POST로 처리해도 된다.
POST는 신이고 무적이다.
라고 할 수도 있겠지만, POST를 남용하는 것은 RESTFul한 API 설계에서 점점 멀어지는 것이라고 할 수 있다. 자유도가 높다는 것은 규칙이 적다는 의미이고, 이는 협업을 어렵게 만들기도 한다는 것을 명심해야 한다.