Portfolio

💬

REST(Representational State Transfer) API 란 무엇인가?

REST API의 개념과 등장 배경

자원을 이름으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미

2000년도 로이 필딩(Roy Fielding)의 박사학위 논문에서 최초로 소개된 개념.

HTTP의 주요 저자 중 한 사람
웹(HTTP)이 설계의 우수성에 비해 제대로 사용되지 못하고 있음에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다.

REST API의 구성요소

자원(Resource) : URI로 표현된다.

URL과 URI의 차이

https://agentsmith.tistory.com

네이버 블로그 중에서도 agentsmith의 티스토리 블로그에 대한 경로를 나타내고 있다.
서버에서는 해당 라우팅에 대한 알맞은 자원을 전송해줄 것이며, 자원의 실제 위치이므로 URL이다.

https://agentsmith.tistory.com/12

agentsmith의 티스토리 블로그에서 12의 ID값을 가지는 자원(포스팅)을 식별하고 있다.
https://agentsmith.tistory.com까지는 자원의 실제 위치이기 때문에 URI임과 동시에 URL이며, /12 부분은 식별자이다.
즉 위 링크는 URL(https://agentsmith.tistory.com)을 포함한 URI(https://agentsmith.tistory.com/12)라고 할 수 있다.

해당 소프트웨어가 관리하는 모든 데이터(문서, 그림 등)
자원의 표현(Representations) : 그 자원을 표시하는 이름

예) DB의 학생 정보가 자원일 때, students를 자원의 표현으로 정한다.

행위(Verb) : HTTP METHOD(GET, POST, PUT, DELETE)

데이터가 요청되어지는 시점에서 자원의 상태(정보)를 이용한 행위
JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.

핵심정리

첫번째 URI는 정보의 자원을 표현해야 한다.

두번째 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

✔️

지키면 좋은 간단한 규칙들

URI Rules

URI는 정보의 자원을 표현해야 한다.

자원 이름은 동사보다는 명사를 사용할 것

컨트롤 자원을 의미하는 URI는 예외적으로 동사를 허용한다.

http://agentsmith.tistory.com/12/duplicate

URI description 규칙

URI 마지막에 / 를 포함시키지 말 것

_(underbar) 대신 -(dash)를 사용할 것

소문자를 사용할 것

행위(method)는 URL에 포함하지 말 것

자원에 대한 행위는 URI가 아닌, HTTP Method로 표현할 것

HTTP Method

GET(조회), POST(생성), PUT(수정), DELETE(삭제) 등

GET /members/delete/1 (X)

DELETE /members/1 (O)

GET /members/show/1 (X)

GET /members/1 (O)

Colllection과 Document을 활용하면 좀 더 직관적인 REST API를 설계할 수 있다.

더 큰 개념으로 생각하면 쉬움. 자원에 대한 부가적인 설명을 나타내는 역할

컬렉션(집단) : sports , 도큐먼트(카테고리) : soccer

http:// restapi.example.com/sports/soccer
http:// restapi.example.com/sports/soccer/players/13

HTTP Method Rules

하나의 자원에 대해 POST, GET, PUT, DELETE 4가지 method는 반드시 제공할 것

OPTIONS, HEAD, PATCH를 사용하여 완성도 높은 API를 만들자.

HTTP status를 method의 리턴값으로 제공할 것

성공 응답은 2XX로 응답한다.

실패 응답은 4XX로 응답한다. (보통 잘못된 URL 접근시 볼 수 있는 에러)

5XX 에러는 절대 사용자에게 나타내지 마라 (보통 DB 또는 코드의 잘못으로 나타나는 에러)

🆚

RequestParam vs PathVariable vs RequestBody

PathVariable


https://agentsmith.tistory.com/{id}
예) https://agentsmith.tistory.com/12

개별 자원을 구분하여 요청할 때 많이 사용하는 방법

RequestParam


https://agentsmith.tistory.com/?filter=lowPrice
https://agentsmith.tistory.com/?startDate=2022-04-20&endDate=2022-04-25
https://agentsmith.tistory.com/?page=3

주로 필터링 또는 페이징을 이용해 자원을 요청할 때 많이 사용하는 방법

필터링 낮은 가격 순으로 보기 / 2022-04-20~2022-04-25 만 보기
페이징 데이터가 너무 많아 한 페이지에 한번에 표시하기 어려운 경우

RequestBody


{
   "id": 1,
   "name": "김수미",
   "team": { "id": 1 },
   "email": "sumikim323@naver.com",
   "position": "intern",
   "createdAt": "2022-04-22",
   "updatedAt": "2022-04-22"
}