RESTful API란?
API 구조를 만들기 위해(API 시스템을 구현하기 위한 아키텍처) 가장 널리 사용되는 형식이다.
리소스(HTTP URI로 정의된)를 구조적으로 깔끔하게 표현한다.(HTTP Method + Payload)
장점 : 서버와 클라이언트 사이에 주고받는 메세지를 스스로 설명하고(self-descriptiveness) 그 자체만으로도 API의 목적이 쉽게 이해된다.
단점 : 표준규약이 없어서 안티패턴(실제 많이 사용되는 패턴이지만 비효율적이거나 비생산적인 패턴)으로 작성되는 경우가 흔하다.
기본 배경 지식
- URI(Uniform Resource Identifier) : 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소 (그림의 요청부분 products)
- HTTP Method : http requset가 의도하는 액션을 정의한 것 (그림의 요청부분 GET)
GET(조회) / POST(등록)- Payload : HTTP Request에서 Server로 보내는 데이터(body) 자체
Request 부분의 URL은 유저가 보내는 것이 아닌 프론트엔드 개발자가 보내는 주소이다.
RESTful API 설계 규칙
( 1 ) URI정보를 명확하게 표현해야 한다.
( 2 ) Resource는 명사를 사용해야 한다.
예) GET/user/1 👉🏻 GET/users/1 : 유저가 한명만 있을 경우엔 앞의 경우도 괜찮지만 많아지면 복수형으로 사용하는게 좋음 (개발자의 소속집단의 컨벤션을 따르면 된다.)
( 3 ) Resource에 대한 행위를 HTTP Method(GET,POST,PUT,DELETE)로 표현한다.
( 4 ) URI에 동사가 포함되서는 안된다.
- GET/user/show/1(X) 👉🏻 GET/users/1
- POST insert/user/2(X) 👉🏻 POST/users/2
( 5 ) Resource 사이에 연관 관계가 있는 경우는 변수를 받을 수 있도록 /리소스/고유ID/관계 있는 리소스를 사용한다.
예) GET/users/{user_id}/profile
( 6 ) 파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다.
예) GET user/1/profile-photo.jpg(X) 👉🏻 GET/user/1/profile-photo (이때, payload의 포맷은 heaers에 accept를 사용한다.)
( 7 ) URI는 "/" 구분자를 통해 자원의 계층 관계를 나타는데 사용한다. 예) GET users/portfolios/ (X)
( 8 ) 불가피하게 URI가 길어지는 경우 -을 사용하여 가독성을 높인다. (언더바는 사용하지 않는다.) 예) /users/3/profile-image
( 9 ) URI 경로에는 대문자 사용을 피하도록 규정하고 있다.
Path parameter & Query parameter
Path parameter
Path parameter는 요청하는 데이터가 식별을 해야만 하는 데이터일 경우 GET/POST/PATCH/PUT를 사용한다. 또 이를 변수로써 활용할 수 있게 해주는 것이다.(유저가 여러명일 때 각자의 url을 만드는게 아님)
( 1 ) GET 메서드를 이용한 예시
(2) POST 와 PATCH 메서드를 사용한 예시
- PATCH 와 PUT의 차이점
- PATCH : 위의 이미지처럼 데이터 내에서 price 한 가지만 값을 수정하는 것
- PUT : id, name, price를 다 수정할 때 사용
(3) DELETE 메서드를 이용한 예시
어떤 상품을 삭제 하고 싶을 경우 상품의 아이디를 전달해 줄 때 body가 아니고 path파라미터에 담아서 준다.
Query parameter
Query parameter는 서칭, 필터링, 오더링, 페이지네이션 등 정렬이 필요할 때 사용한다.
( 1 ) Filtering
( 2 ) Ordering : 상품순, 가격순, 인기순 등 정렬할 때
( 3 ) Pagenation : 한 페이지를 로딩할 때 페이지 단위로 보여주고 싶은 상품들을 나눌 때
(4) Searching : 전체 유저 중 한 사람의 유저를 찾는 경우
Path parameter vs Query parameter
Q .만약 사용자가 상품을 검색할 때, 데이터베이스에 상품번호 3번이 없을경우 반응은?
A. Path parameter : 404 NOT FOUND
A. Query parameter : 비어있는 NEST
결론 : 오류가 나면 안되는 기능을 사용할 때(흰 티를 검색했지만 상품이 없을 때 빈화면을 뜨게 하는 것) - Query parameter를 사용하고, 요청하는 데이터가 식별을 해야만 하는 데이터일 경우 Path parameter를 사용한다.
