REST API URL 설계 규칙과 REST 클라이언트 활용법

---

1. REST API URL 설계 규칙

RESTful API의 URI(Endpoint)는 자원을 식별하는 방식으로 구성되어야 하며, 예측 가능하고 명확한 구조를 가져야 합니다.

1-1. URI 설계 원칙

규칙	설명
명사 사용	URI는 자원을 나타내므로 명사를 사용합니다.
소문자 사용	대소문자 구분이 있으므로 일관되게 소문자 사용
하이픈(-) 사용	단어 구분은 언더바(_) 대신 하이픈 사용
계층적 구조	URI는 계층적(트리형)으로 설계합니다.
확장자 제외	.json, .xml 등 확장자 생략 권장 (Header로 명시)

1-2. 예시 URI 패턴

설명	예시 URI
전체 사용자 조회	/users
특정 사용자 조회	/users/123
특정 사용자의 주문 목록	/users/123/orders
특정 주문 상세	/users/123/orders/456

❌ 잘못된 예시: /getAllUsers, /doDeleteUser/123 ✅ RESTful 예시: /users, /users/123

---

2. 버전 관리 전략

API는 시간이 지나며 변경될 수 있기 때문에 버전 관리가 매우 중요합니다.

2-1. URI 버전 방식

GET /v1/users
GET /v2/users

• 가장 흔하게 사용되는 방식
• URI 구조 내에 명시되므로 직관적임

2-2. Header 기반 버전

GET /users
Accept: application/vnd.company.v1+json

• 클라이언트가 Header에 명시
• URI는 깔끔하지만 관리 복잡도 증가

2-3. 쿼리파라미터 방식 (비권장)

GET /users?version=1

• 가독성 떨어지고 REST 원칙 위배 가능성 있음

---

3. HTTP 상태 코드 정리

REST API는 처리 결과를 HTTP 상태 코드로 명확히 알려주는 것이 중요합니다.

3-1. 상태 코드 요약

코드	의미	설명
200	OK	요청 성공 (조회 등)
201	Created	새 자원 생성 성공
204	No Content	요청 성공, 응답 본문 없음
400	Bad Request	잘못된 요청 (파라미터 오류 등)
401	Unauthorized	인증 실패 (토큰 없음 등)
403	Forbidden	권한 없음
404	Not Found	자원 없음
500	Internal Server Error	서버 내부 오류

예시: POST 요청 후 201 Created 반환 + Location 헤더에 새 URI 포함

---

4. REST 클라이언트 소개 (Postman & Insomnia)

REST API 테스트를 위한 대표적인 도구는 Postman과 Insomnia입니다.

4-1. Postman

• GUI 기반 API 테스트 툴
• GET/POST/PUT/DELETE 모두 지원
• 요청 이력 관리, 환경변수, 테스트 스크립트 작성 가능
• 팀 협업에 유리함

4-2. Insomnia

• 가벼운 인터페이스의 REST 클라이언트
• GraphQL, WebSocket 등도 지원
• 다크모드 중심의 개발 친화적 UX
• 빠른 응답 테스트 및 JSON 편집에 특화

---

5. 실습: REST API 호출 실전 예제

5-1. 요청

POST /users
Content-Type: application/json

{
  "name": "홍길동",
  "email": "hong@example.com"
}

5-2. 응답

HTTP/1.1 201 Created
Location: /users/124

{
  "id": 124,
  "name": "홍길동",
  "email": "hong@example.com"
}

5-3. 오류 응답 예

HTTP/1.1 400 Bad Request

{
  "error": "이메일 형식이 올바르지 않습니다."
}

---

마무리

이번 회차에서는 REST API를 실무에서 RESTful하게 구성하고 관리하는 법에 초점을 맞췄습니다.

• REST URI는 자원 중심, 명사 중심으로
• 상태 코드를 정확하게 전달하여 클라이언트와의 의사소통 명확화
• Postman/Insomnia를 활용한 API 테스트 루틴 확보

---