:: RESTful API
프론트엔드와 백엔드 간의 엔드포인트를 맞추기 위한 규약에 대한 내용
01. RESTful API란?
API 시스템을 구현하기 위한 아키텍쳐 중에 가장 널리 사용되는 형식 → 효율적이고 저비용
아키텍쳐 예시) GraphQL, SOAP, gRPC, REST ... 등
SOAP vs. REST
- SOAP: HTML 같이 생긴 XML 형식으로 정보를 주고받음 → 보기에 직관적이지 않음
- REST: 직관적인 JSON 형식으로 정보를 주고받음
GraphQL
query에 원하는 정보를 입력 → 단 하나의 URL로 요청
- URL이 단 하나로 수렴될 수 있다
- FB, IG에서 사용 (FB이 개발)
- 모든 데이터를 항상 가지고 있어야함 → RESTful 대비 연산속도 느림
REST = Representational State Transfer
웹 상의 여러 리소스를 HTTP URI로 표현, 그 리소스에 대한 행위를 HTTP Method로 정의.
→ 리소스(목적어; uri)를 어떻게 한다(동사; method + payload)를 구조적으로 깔끔하게 표현할 수 있음
👍 Self-descriptiveness : 그 자체만으로 목적이 쉽게 이해된다
👎 Anti-pattern : 표준 규약이 없어 안티패턴(실제 많이 사용되지만 비효율적이거나 비생산적인 패턴)으로 작성되는 경우가 많다.
💡 기본 배경 지식
1. URI (Uniform Resource Identifier)
해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
2. HTTP Method
HTTP request가 의도하는 action을 정의한 것
3. Payload
HTTP request에서 server로 보내는 데이터 (body)
02. RESTful API 설계 규칙
URI 정보를 명확하게 표현해야 한다.
- resource는 명사를 사용 (대부분 복수형)
ex)GET /users/1
resource에 대한 행위를 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
- URI에 method가 포함되면 안됨
ex)GET delete/users/1→DELETE users/1
- URI에 동사가 포함되서는 안된다
ex)GET /users/show/1→GET users/1
ex)POST insert/users/2→POST /users/2
resource 사이에 연관관계가 있는 경우 (큰 집합 → 작은 집합 순으로)
- /리소스/고유ID/관계있는리소스
ex) GET /users/{user_id}/profile
파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다 (API = URL로 사용됨 → 오류 발생)
GET users/1/profile-photo.jpg→GET users/1/profile-photo- headers에서 accept를 통해 payload의 포맷을 정의한다
URI는 /구분자를 사용하여 계층관계를 나타낸다
URI 마지막 문자로 /를 포함하지 않는다 (이후 쿼리 파라미터 붙이기 위해)
ex) GET users/portfolios/ (X)
불가피하게 URI가 길어지는 경우 -을 사용하여 가독성을 높인다
대부분의 문서 뷰어는 클릭 가능한 텍스트 (하이퍼텍스트) 를 밑줄로 표현 → _는 혼동됨
URI 경로에는 대문자 사용을 피해야함
03. Path parameter, Query parameter
💖 Path parameter
→ 자원 간의 계층 구분을 위해 /를 사용
POST를 통해 auto-increment를 통해 id를 부여받고 입력이 됨
PATCH를 통해 1번 product에 대한 가격을 업데이트함
DELETE를 통해 단 하나의 정수값만 보내주어서 삭제할 수 있음
💡 PUT, PATCH - update 작업을 수행하는 메서드
PATCH : 데이터의 일부만 입력받고 일부만 update 한다
PUT : 전체 데이터를 입력받아 덮어쓴다
💖 Query parameter
1️⃣ Filtering
GET /products?price=3000원
GET / products?price=3000원&name=사과
→ price가 3000원이고, name이 사과인 제품만 필터링
2️⃣ Ordering
GET /products?ordering=-id
→ 내림차순으로 정렬
3️⃣ Pagination
GET /products?offset=0&limit=100 → offset: 시작점, limit: 끝점 → 0부터 100번까지만 가져온다
4️⃣ Searching
GET /users?search=홍길동 → users 중에서 홍길동이 매칭 되는 항목만 검색
🧑🎓 Path vs Query
GET /products/3 vs GET /products?id=3
→ 결과는 똑같음... 언제 어떤 방법을 사용?
⇒ Path parameter 사용 : id 3번에 대한 가장 단순한 형태이기 때문
💡 Best Practice
Query parameters → Filtering, Sorting, Searching
04. RESTful 하지 못한 API 설계 예시
GET http://10.58.4.1:8000/detail_page
→ GET http://10.58.4.1:8000/product
명시적이지 않음 + _ 사용 불가
GET http://10.58.4.1:8000/main_page
→ GET http://10.58.4.1:8000/products
GET http://10.58.4.1:8000/find/product
→ GET http://10.58.4.1:8000/product
(동사 안됨!)
POST http://10.58.4.1:8000/add/product
→ POST http://10.58.4.1:8000/product
(불필요한 동사)
POST http://10.58.4.1:8000/product_reviews
→ POST http://10.58.4.1:8000/products/1/reviews
(계층이 드러나게 짜야함)
POST http://10.58.4.1:8000/product_filter
→ GET http://10.58.4.1:8000/products?name=
(GET 함수로 query parameter를 사용해야함)
