🎯 목차

1. 리소스 중심 설계
2. HTTP 메서드의 적절한 사용
3. 일관된 URI와 데이터 구조
4. 상태 코드의 명확한 사용
5. 필요한 데이터만 반환
6. 결론

리소스 중심 설계

• API 설계는 작업(Action)이 아닌 데이터 리소스를 중심으로 설계해야 한다.
• URI는 리소스를 나타내는 명사로 구성되며, 데이터를 계층적으로 표현한다.
• 리소스 예:
  • /users : 사용자 목록
  • /users/1 : 특정 사용자
  • /users/1/orders : 특정 사용자의 주문 목록
• 잘못된 URI 설계:
  • /getUsers , /createOrderForUser/1
    → 동사를 사용하면 리소스가 아닌 동작에 의존하게 되기 때문에 API 확장성이 낮아진다.

HTTP 메서드의 적절한 사용

• 전 글에서도 적었듯 각 HTTP 메서드는 표준화된 작업을 수행하도록 설계되어 있다.
  • GET : 리소스 조회.
  • POST : 새 리소스 생성.
  • PUT : 리소스 전체 교체 또는 새 리소스 생성.
  • PATCH : 리소스 일부 수정.
  • DELETE : 리소스 삭제.
• 예시:
  • 사용자를 생성: POST /users
  • 사용자 정보 수정: PUT /users/1
  • 사용자 삭제: DELETE /users/1

일관된 URI와 데이터 구조

• URI는 규칙성을 가져야 하며, 가독성과 예측 가능성이 높아야 한다.
  • 모든 리소스는 복수형 명사를 사용하는 것이 좋다.
    • 예: /products, /orders, /categories
  • 소문자만 사용하고, 공백 대신 하이픈(-)을 사용하는 것이 좋다.
    • 예: /product-details (올바름), /Product_Details (잘못됨)
  • 슬래시(/)로 계층 구조를 표현하는 것이 바람직하다.
    • 예: /users/1/orders (올바름)

상태 코드의 명확한 사용

• 각 요청에 적절한 상태 코드를 반환함으로써, 요청 성공 여부와 문제의 원인을 파악할 수 있도록 해야 한다.
  • 200 OK : 요청 성공
  • 201 Created : 새 리소스 생성 성공
  • 204 No Content : 성공했으나 본문 데이터 없음
  • 400 Bad Request : 요청 형식이 잘못됨
  • 404 Not Found : 리소스를 찾을 수 없음
  • 500 Internal Server Error : 서버 내부 오류

필요한 데이터만 반환

데이터를 반환 할 때는 클라이언트에게 필요한 데이터만 반환함으로써 네트워크의 부담을 줄이고 성능의 최적화를 도모함이 바람직하다. 이를테면 전체 사용자 데이터를 반환할 필요가 없을 경우, 필요한 필드만 선택적으로 반환하는 것이 좋다.

• 예시 : GET /users?fields=id,name,email

결론

요약하자면 HTTP API 설계는 클라이언트와 서버 간의 명확하고 직관적인 데이터 교환을 지원하기 위한 핵심 요소이다. 또한 RESTful 설계 원칙을 따르면 확장 가능하고 유지보수가 쉬운 API를 만들 수 있고, 필터링, 정렬, 페이지네이션 등과 같은 기능을 추가하면 데이터 관리 효율성과 사용자 경험을 높일 수 있다고 할 수 있겠다.