API 설계 시 클라이언트로부터 값을 받아와야 할 때마다, 어떤 방식으로 가져오는 것이 좋을지 특별한 기준 없이 결정했던것 같아 규칙을 찾아보았다.

Path Params

/api/v1/running-crews/{running-crew-id}/path/{other}

Path Params 란 앤드포인트의 일부이다. 위의 예시에서 running-crew-id 나 other 등으로 서버에게 값을 전달하는 방식이다.

• 특정 리소스를 정의할 필요가 있을 때 → 데이터 하나의 정보가 필요할 때

Query String

/api/vi/running-crews?id={running-crew-id}

Query String 이란 앤드포인트 이후에 물음표(?) 뒤에 key-value 값으로 주어지는 방식이다. 위의 예시에서는 id 가 running-crew-id 라는 정보를 서버에게 전달할 수 있다.

• 여러 조건을 설정할 필요가 있을 때 → 정렬, 필터링, 검색 등

Body

{
		id : {running-crew-id}
}

URL 이 아닌 Body 로 값을 전달하는 방식이다. JSON 의 key-value 형식으로 표현한다. 위의 예시에서는 id 가 running-crew-id 라는 정보를 서버에게 전달할 수 있다.

• URL 로 표현할 수 없는 데이터 → XML, MultiForm
• 그 외의 모든 경우

정리

리소스의 상세정보를 조회할 때는 Path Params 로, 검색하거나 필터링을 걸어야 하는 상황에서는 Query String 을, 그 외의 모든 경우에는 Body 형식을 사용하자.

• 참고 사이트