✅ REST API란?
REST(REpresentational State Transfer)란 웹에 존재하는 모든 자원(resource, ex. 이미지, 동영상, 데이터)에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 또는 규칙을 가리킵니다.
현재 가장 널리 사용되고 있습니다.
RESTful API는 REST 특징을 지키면서 API를 제공한다는 뜻입니다.
쉽게 말해,
프론트엔드에서 백엔드 API를 호출할 url을 어떻게 만들것인가?"에 대한 이야기라고 생각할 수 있습니다.
✅ RESTful API 설계 규칙
RESTful한 API를 제공하기 위해서는 몇가지 원칙이 있는데요.
원칙 6가지와 url이름을 규정하는 방법에 대해 알아보겠습니다.
📌REST 원칙 6개
Uniform Interface (중요)
-
하나의 자료는 하나의 url로 표현해야합니다.
-
url만 보고 어떤 페이지이며, 어떤 정보가 담겨있을 것이라고 예측을 할 수 있어야 합니다.
-
요청과 응답은 정보가 충분히 들어가있어야 합니다.
Client - Server 역할 구분
- 브라우저는 요청만, 서버는 응답만 해야합니다.
Stateless
- 요청1, 요청2 즉 각각의 요청들은 의존성이 없어야 함.
Cacheable
- 서버에서 보내주는 정보들은 캐싱이 가능해야 합니다.
Layered System
- 컴포넌트가 그룹화가 되고 계층이 구조화가 이루어져있어야 합니다.
Code on Demand (optional)
보통 서버에서 정적인 데이터를 클라이언트로 보내면 클라이언트가 가공하여 사용합니다.
그런데 서버에서 보내는 데이터를 실행 가능한 코드로 클라이언트에게 보내서 바로 실행하는 것을 말합니다.
클라이언트의 요청에 따라 소통이 필요한 사항입니다.
📌 이름짓기 원칙
url 명사로 작성하기
상품의 정보를 얻어서 페이지에 띄운다고 하여 https://sangwoong/get/product라고 작성하지 않습니다.
대신 https://sangwoong/products 라고 작성합니다.
하위 문서를 명시할 때는 파일확장자(.html) 사용하지 않기
보여주는 페이지가 product.html이라고 해도 url에는 파일 확장자를 사용하지 않습니다.
띄어쓰기를 표시할 땐 대시(-) 사용하기
https://sangwoong/product_list와 같이 언더바(_)를 사용하게 되면 하이퍼링크를 사용할 때 언더바를 사용한 것인지, 공백이 포함되어 있는 것인지 명확하지 않을 수 있습니다.
https://sangwoong/product-list 혹은
https://sangwoong/product/list로 url을 작성해줍니다.
자료 하나 당 하나의 url 사용하기
url을 보고 어떤 정보가 있는지 예측할 수 있게 url을 작성해줍니다.
https://sangwoong/products에서는 products와 관련된 자료를 보여주면 되겠죠?
✅ Path parameter, Query parameter
📌 Query parameter
유저의 id가 123인 정보를 가져와줘!
위의 예시처럼 웹 페이지의 url 주소를 자세히 보면 종종 ? 가 포함되어 있는 것을 많이 봤을텐데요.
이 물음표는 단순한 문자열이 아니라 특정한 기능을 수행하고 있습니다.
물음표 뒤에는 늘 key = value 형식의 문자열이 따라옵니다.
이것을 Query parameter 라고 부릅니다.
주로 데이터를 조건으로 거르거나 (filtering),
특정 방식으로 정렬하거나 (sorting),
검색 (searching) 하고자 하는 경우에 활용됩니다.
📌 path parameter
위의 예시와 같이 url 마지막 부분에 숫자만 포함되어 있는 것도 많이 볼 수 있습니다.
이미 API에서 요청 받을 정보의 key에 대한 value값을 변수로 사용하는 것입니다.
만약 user의 id 값을 통해 해당 데이터를 보여주는 것이라면, 클라이언트에서 user 데이터의 id가 123인 정보를 서버에게 요청하는 것이죠.
이처럼 경로를 변수로 사용하는 Path parameter는 구체적인 데이터 정보 (resource)를 식별하는데 활용됩니다.
📌 언제 사용할까?
만약 특정 데이터를 식별하고 싶으면 Path Variable을 사용하고,
반면, 앞에서 언급했듯 정렬이나 검색, 필터링을 한다면 Query Parameter를 사용하는 것을 이상적인 방법이라고 합니다.
API 기능에 맞는 방법을 선택하는 것이 중요할 것 같습니다.
