REST API (path parameter, query parameter)

WHAT REST

 

- REST : Representational State Transfer의 약어(상태를 전달하는 것을 나타내는 방법)

- 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 것을 의미

- [구성]

 1) 자원(Resource) - URI(Uniform Resource Indentifier)

 2) 행위(Verb) - HTTP METHOD

 3) 표현(Representations)

 

WHAT API

- Application Programming Interface의 약어

- 정보 사용자가 원하는 것에 도달할 수 있도록 한 인터페이스

- 애플리케이션 소프트웨어의 구현 방식을 몰라도 사용자는 API를 통해 사용 가능

- 정보 제공자와 정보 사용자 간 소통하기 위한 하나의 인터페이스 장치

 

WHAT REST API

- REST를 기반으로 서비스 API를 구현한 것

- RESTful하다 --> REST 구조 스타일로 API가 이루어진 서비스

 

[URI 기본 설계 규칙]

1. 슬래시 구분자(/)는 계층 관계를 나타낼 때 사용

2. URI 마지막 문자로 슬래시(/)를 포함하지 않음

3. 밑줄(_) 대신 하이픈(-) 사용

4. URI경로는 소문자로만 작성

5. 파일 확장자는 URI에 미포함

6. CRUD 행위(verb)는 포함하면 안됨

 

[리소스 원형 종류]

 1. 도큐먼트 : 데이터베이스의 row 단위 또는 리스트 컬렉션의 하나의 객체단위로 단일 정보를 포함하고 있는 데이터

 2. 컬렉션 : 도큐먼트들의 집합. 관리주체는 서버이고 컬렉션은 클라이언트 단에서 새로운 리소스를 제안해서 올릴 수도 있지만 결정은 서버가 한다.

 3. 스토어 : 컬렉션과 같이 도큐먼트들의 집합이며 관리주체는 클라이언트. 클라이언트는 기존의 리소스를 스토어에 추가하거나 삭제,변경할 수 있다.

 4. 컨트롤러 : 컬렉션, 스토어의 메서드(함수)기능. HTTP METHOD(CRUD)를 제외한 특정 기능을 요구할 때 사용.

 

리소스 원형을 url에 표현할 때, 도큐먼트는 단수 명사로 표현하고, 컬렉션과 스토어는 복수 명사를 사용해야하고 컨트롤러는 동사여야 한다.

 

Path Parameter

URL은 고유한 자원을 지칭할 수 있다. 그런데, URL중 컬랙션 내의 특정 도큐먼트를 식별하고자 할 때, 그 도큐먼트를 변수처럼 지정하요 사용할 수 있는데 이 변수의 이름을 path parameter라고 한다. 보통 어떤 resource를 식별하고 싶을 때 사용한다.

 

[예시]

→ https://map.naver.com/v5/entry/place/:placeId

• https://map.naver.com/v5/entry/place/11583199
• https://map.naver.com/v5/entry/place/1353885407
• https://map.naver.com/v5/entry/place/12017005

 

Query Parameter

Query Parameter는 url에서 특정한 조건을 주고 싶을 때 사용하는 매개변수 유형이다. URL 끝에 물음표(?)뒤에 나타나며, and 기호(&)로 구분된 '이름=값' 쌍으로 구성된다. 보통 GET, DELETE 요청에서만 사용하고 유일한 값을 식별하기 위한 용도가 아닌 옵션을 줄때 사용한다.

 

[사용]

- 데이터 필터링

- 데이터 정렬

- 데이터 수 조절(페이지네이션)

- 검색 등

 

1. 필터링

 

2. 정렬

 

3. 데이터 수 조절(Pagenation)

데이터베이스에 저장된 모든 데이터를 클라이언트가 한 번에 모두 호출하여 사용하면 통신 속도가 매우 저하될 수 있다. 그래서 한 번에 필요한 만큼만 데이터를 호출하는 것이 효율적이다. 이런 상황에서 필요한 데이터의 시작점과 끝 점을 쿼리 스트링을 통해 전달할 수 있는데,

관습적으로 데이터의 시작점을 "offset", 주고 받고자 하는 데이터의 개수를 "limit"으로 정한다고 한다.

 

 

4. 검색

데이터베이스에 저장된 데이터에서 필요한 정보 객체를 특정 키워드로 "필터링"할 때 사용한다. 통상적으로 "search"라는 키워드를 사용한다.

[예시]

• [GET] /products?price=3000
• [GET] /products?ordering=-id
• [GET] /products?offset=0&limit=100
• [GET] /products?serach=홍길동

Query Parameter를 이용해 생성된 위 4가지 API는 기본적으로 [GET]/products와 동일한 API를 호출하는 내용이다. 따라서 API는 하나로 작성되어야 하고 query string을 변수로 받아서 각각의 조건마다 필요한 데이터를 전송해야 한다.

 

만약 path parameter를 통해 [GET]/products/1 API를 만들게 된다면 [GET]/products API와는 다른 API로 만들어야 된다는 점을 잊으면 안된다.

 

또한, query parameter에 대해 클라이언트에서 값을 주지 않을 때를 대비해서 기본값(default)을 설정할 수 있고

동일한 키의 값으로 여러 값을 전달할 경우, 서버에서는 배열로 값을 받을 수 있다.

• [GET] /products?size=230&size=240&size=280 → { size : [230, 240, 280] }

 

[실제 사용 예시 - 무신사]

https://www.musinsa.com/categories/item/001?d_cat_cd=001&brand=&list_kind=small&sort=pop_category&sub_sort=&page=2&display_cnt=90&group_sale=&exclusive_yn=&sale_goods=&timesale_yn=&ex_soldout=&kids=&color=&price1=&price2=&shoeSizeOption=&tags=&campaign_id=&includeKeywords=&measure=