REST API 규칙!

1. 명사를 사용하라!

URI는 리소스를 식별하는데 사용된다.

올바른 URI: /products, /users
잘못된 URI: /getProducts, /createUser

단수 명사 대신 복수 명사를 사용

Best: /products/123
Worst: /product/123

소문자 사용

📌 일관성과 가독성을 유지

대부분의 웹 서버 및 프레임워크는 URL을 소문자로 강제 변환하도록 구현되어 있다. 이는 URL의 일관성을 유지하고, 서버에서 요청을 처리할 때 일관성 있게 처리할 수 있도록 한다.

언더바( _ ) 대신에 하이픈( - )을 사용을 권장

private_products ➡ private-proudcts
URL은 하이퍼링크가 걸렸을 때 밑줄이 그어지는 경우가 종종 있다

💡 프라그먼트 식별자(#)를 사용하면 리소스 식별이 어려워진다.(ex. /products#123)

2. 용도에 맞는 HTTP 메서드 사용하기

/products [GET] // 제품 목록 조회
/products/index [GET] // 제품들 중 인덱스가 n인 제품 정보를 조회

/products [POST] // 새 제품을 생성

/products/123 [PUT] // 인덱스가 1123인 제품을 완전히 교체

/products/123 [DELETE] // 인덱스가 123인 제품을 삭제

👉🏻 HTTP 메서드

리소스 간의 계층 관계는 슬래시(/)를 이용

: 부모-자식 관계를 이해하기 쉽도록

/products/123/reviews

HTTP 메서드별 Request Body 사용 여부

GET, DELETE 메서드는 보통 Request Body에 데이터를 담지 않는다. 따라서 GET, DELETE의 HTTP 메서드를 사용할 때는 Query Parameter나 Path Paramater를 활용하자.

-- Query Parameter
GET /api/products?category=electronics

-- 삭제할 리소스를 URI에 명시
DELETE /api/products/123

-- Request Body
POST /api/products
{
    "name": "Smartphone",
    "price": 499.99
}

상황별 어노테이션 사용

• @RequestParam 쿼리 매개변수 받을 때
• @PathVariable 경로에서 변수 받을 때
• @RequestBody 요청 본문에서 데이터 받을 때
• @RequestPart 멀티파트 요청에서 파일 업로드나 여러 파트로 나눠진 요청을 처리할 때 사용

Path Parameter

어떤 resource를 식별하고 싶을 경우나 다수의 resource 중 특정 resource를 가리키는 경우 사용한다

GET /api/users/{userId}

Query Parameter

필터링, 정렬, 옵션 설정, 페이지네이션

-필터링 (Filtering)
GET /products?category=laptops

-정렬 (Sorting)
GET /products?sort=price&order=asc
// 제품 목록을 가격을 기준으로 오름차순으로 정렬

-옵션 설정 (Option Setting) & 페이지네이션 (Pagination)
GET /products?pageSize=10&details=true
// 검색 결과를 페이지당 10개로 제한하고, 제품의 세부 정보를 추가로 반환

➕

• 응답 포맷 지정 가능하게 하라: 클라이언트가 응답 포맷을 선택할 수 있도록 헤더에 Accept를 사용하고, 응답의 기본 포맷을 JSON으로 지정하는 것이 일반적입니다.

• SSL을 사용하여 보안을 유지하라: 중요한 정보를 다루는 API의 경우 HTTPS를 통해 통신을 암호화하고 보안을 강화해야 합니다.

• 버전 관리를 지원하라: API의 변경 사항이나 업데이트를 관리하기 위해 버전 관리를 제공하고, 이전 버전과의 하위 호환성을 유지하도록 노력해야 합니다.

• API 문서화를 제공하라: API를 이해하기 쉽게 문서화하고, Swagger 또는 OpenAPI와 같은 도구를 사용하여 API 스펙을 자동으로 생성하는 것이 좋습니다.

• 에러 처리를 명확하게 하라: 에러 메시지와 에러 코드를 명확하게 정의하고, 클라이언트가 문제를 해결하는 데 도움이 되도록 에러 정보를 제공해야 합니다.