API 엔드포인트 구성 방법

RESTful API란?

REST란?

• 자원(Resource)을 중심으로 HTTP의 기본 원리(GET, POST, PUT, DELETE 등)를 활용해 API를 설계하는 방식
• "URL로 자원을 식별하고, HTTP 메서드로 동작을 정의한다"는 것이 핵심

RESTful API란?

• REST 원칙을 잘 지켜서 설계한 API를 RESTful API라고 부름
• 즉, 리소스 중심적이고 일관성 있는 API 설계 방식

특징

• 클라이언트 - 서버 분리
  서버는 데이터와 로직, 클라이언트는 UI와 사용자 경험 담당
• 무상태성(Stateless)
  서버가 클라이언트 상태(Session)를 저장하지 않음. 요정 안에 필요한 정보 포함
• 캐시 가능성
  HTTP 캐싱 활용 가능 (응답에 Cache-Control, ETag 등)
• 계층 구조
  클라이언트는 중간 서버(프록시, 게이트웨이)를 몰라도 됨
• 인터페이스 일관성
  리소스를 URI로 명확히 식별, 동일한 형식(JSON 등)으로 응답

---

RESTful API 설계 규칙

HTTP Method

• 리소스 지향: 명사는 복수형, 계층은 슬래시(/)로 표현

GET: 조회 (받겠다)
POST: 리소스 생성 (보내겠다)
PUT: 리소스 전체 갱신(넣겠다)
PATCH : 리소스 일부 갱신
DELETE: 리소스 삭제 (지정한 서버의 파일을 삭제하겠다)

설계 예시

CRUD	HTTP	URI	멱등 여부
전체 리소스 조회	GET	/articles	O
특정 리소스 조회	GET	/articles/{id}	O
리소스 생성	POST	/articles	X
리소스 전체 수정	PUT	/articles/{id}	O
리소스 일부 수정	PATCH	/articles/{id}/like	X

👉 추가 개념 : 멱등성(Idempotency)

• 멱등성은 동일한 요청이 여러 번 반복해도 서버의 상태가 변하지 않는 성질을 말한다.
• REST API에서는 중복 요청 시 의도치 않은 부작용을 막기 위해 사용되는 개념이다.

HTTP 응답 상태 코드

자주 사용되는 HTTP 상태 코드

상태 코드	설명
200	요청 성공 (조회, 수정 등)
201	리소스 생성 성공 (POST 요청)
400	잘못된 요청 (파라미터 오류 등)
401	인증 필요 (로그인되지 않은 경우)
403	접근 권한 없음 (보통 400, 404 사용 권장)
404	리소스를 찾을 수 없음
405	허용되지 않은 Method 사용
301	리소스 URI 변경됨 (Location 헤더로 새 URI 제공)
500	서버 내부 오류

---

REST API 디자인 가이드

RESTful 설계 시 가장 중요한 항목은 두 가지로 요약할 수 있다.

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

---

1) URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다 명사를 사용)

PUT /members/delete/1   (x)
DELETE /member/1        (o)

👉 URI에는 delete 같은 행위 표현이 들어가면 안 된다.

2) 자원에 대한 행위는 HTTP Method로 표현한다.

• 회원 정보 조회

GET /member/show/1   (x)
GET /member/1        (o)

• 회원 추가

GET /members/insert  (x)
POST /member         (o)

• URI에 행위가 들어갈 경우 POST 메소드로 통일

PUT /member/active   (x)
POST /member/active  (o)

---

URI 설계 시 주의할 점

• 슬래시(/)는 계층 관계를 나타낼 때 사용

/api/houses/apartments
/api/animals/mammals/whales

• URI의 마지막 문자로 슬래시를 포함하지 않음
  URI는 고유한 리소스 식별자이므로, 경로 마지막에 /는 혼동을 줄 수 있음

• 하이픈(-)은 가독성을 높이는 데 사용
  긴 URI일 경우 단어 구분에 활용

• 밑줄(_)은 사용하지 않음
  글꼴에 따라 보기 불편하고 문자가 가려질 수 있음

• URI 경로는 소문자 사용
  대소문자에 따라 다른 리소스로 인식될 수 있음

• 파일 확장자는 포함하지 않음

http://restapi.example.com/members/1/image.jpg   (x)

GET /members/1/photo HTTP/1.1
Host: restapi.example.com
Accept: image/jpg                               (o)

---

리소스 간의 관계 표현

리소스 간 연관 관계는 보통 다음과 같이 표현한다.

/리소스명/리소스ID/관계가 있는 다른 리소스명

• 일반적으로 소유의 관계를 표현할 때

GET /articles/{id}/reviews

• 관계명이 애매하거나 구체적 표현이 필요할 때

GET /users/{userid}/likes/devices

참조

https://velog.io/@couchcoding/%EA%B0%9C%EB%B0%9C-%EC%B4%88%EB%B3%B4%EB%A5%BC-%EC%9C%84%ED%95%9C-RESTful-API-%EC%84%A4%EA%B3%84-%EA%B0%80%EC%9D%B4%EB%93%9C