URI 컨트롤 , API 설계하기

API 설계 시, URI(Uniform Resource Identifier)를 사용하는 것은 API의 각 기능에 명확한 주소를 부여하여 클라이언트가 요청할 수 있도록 하는 방법이다.

이 때 URI를 잘 설계하는 것이 중요하며, RESTful API 설계 원칙에 따라 URI를 만들면 이해하기 쉽고 유지보수하기 쉬운 API를 만들 수 있다.

---

리소스 기반 설계

• URI는 리소스를 나타내도록 설계해야 한다. 리소스는 데이터베이스의 테이블과 비슷한 개념으로, 예를 들어 사용자(user), 제품(product), 주문(order) 등이 있을 수 있다.
• 리소스를 나타낼 때는 명사를 사용해야 하며, 동사를 사용하지 않는 것이 좋다.

GET /users              # 모든 사용자 조회
GET /users/{id}         # 특정 사용자 조회
POST /users             # 새로운 사용자 생성
PUT /users/{id}         # 특정 사용자 정보 업데이트
DELETE /users/{id}      # 특정 사용자 삭제

 

계층 구조 사용

• 관련된 리소스를 계층 구조로 나타낼 수 있다. 이를 통해 부모-자식 관계를 명확히 할 수 있다.

GET /users/{id}/orders          # 특정 사용자의 모든 주문 조회
GET /users/{id}/orders/{orderId} # 특정 사용자의 특정 주문 조회
POST /users/{id}/orders         # 특정 사용자에 대한 주문 생성

 

필터링 및 정렬

• URI에 쿼리 매개변수를 사용하여 데이터를 필터링하거나 정렬할 수 있다.

GET /products?category=electronics   # 'electronics' 카테고리의 제품 필터링
GET /products?sort=price&order=asc   # 가격을 기준으로 오름차순 정렬

 

HTTP 메소드 사용

RESTful API에서는 HTTP 메소드를 사용하여 동작을 정의한다.

• GET: 리소스 조회
• POST: 리소스 생성
• PUT: 리소스 업데이트
• DELETE: 리소스 삭제
• PATCH: 리소스의 부분 업데이트

GET /books               # 모든 책 목록 조회
POST /books              # 새로운 책 추가
PUT /books/{id}          # 특정 책의 정보 수정
DELETE /books/{id}       # 특정 책 삭제

 

상태 코드 사URI 설계뿐만 아니라 API에서는 적절한 HTTP 상태 코드를 반환해야 한다.

• 200 OK: 요청이 성공적으로 처리
• 201 Created: 리소스가 성공적으로 생성
• 204 No Content: 요청이 성공적으로 처리되었으나 반환할 콘텐츠가 없음
• 400 Bad Request: 잘못된 요청
• 404 Not Found: 요청한 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버 내부 에러

 

버전 관리

• API가 발전하면서 버전을 관리하는 것이 중요하다. 보통 URI에 버전을 명시한다.

GET /api/v1/users        # v1 버전의 사용자 API
GET /api/v2/users        # v2 버전의 사용자 API

 

URI 설계 시 주의 사항

• URI는 항상 소문자를 사용
• 단어 사이에는 대시(-)를 사용한다. 언더스코어(_)는 사용하지 않는다.
• URI는 간결하게 유지하며, 지나치게 길어지지 않도록 한다.
• RESTful API에서는 행동(동사)을 URI에 포함하지 않는다. 행동은 HTTP 메소드로 나타낸다.

 

 

GET /api/v1/articles            # 모든 기사 조회
GET /api/v1/articles/{id}       # 특정 기사 조회
POST /api/v1/articles           # 새로운 기사 생성
PUT /api/v1/articles/{id}       # 특정 기사 업데이트
DELETE /api/v1/articles/{id}    # 특정 기사 삭제
GET /api/v1/users/{id}/articles # 특정 사용자의 기사 목록 조회

위의 설계 정책들을 종합적으로 볼 때, 이렇게 구조를 사용하면 클라이언트가 API를 이해하고 사용하는데 도움이 되고,
RESTful API의 기본 원칙을 따르면 유지보수와 확장이 용이한 API 설계를 할 수 있다.
실무에서는 모든 규칙들을 따르기 어렵기 때문에 팀, 조직의 문화에 따라 적절히 사용하면 된다. 이러한 공식적인 설계 규칙이 있기 때문에 최대한 맞추려고 노력해보는 것이 좋은 것 같다.