API 설계 원칙

 

Today I Learn ✍🏼 

 

• 오늘 하루 가장 인상 깊었던 배움에는 뭐가 있었지?
  • endpoint를 정하는데 의문이 들었다
  • patch 언제 쓰는거지?
  • 단일책임원칙은 class 범위 아니야?

 

• 그 배움까지 다가가는데 어떤 어려움이 있었지?
  • 회사 팀에 따라 달리지는 것 아닌가? 라고 생각하고 넘어갔었다.
  • 그러나 팀원이 왜 같은 endpoint로 patch를 해도 되는데 이유를 물어서 생각을 하게 되었다.

 

• 그 어려움을 해결하기 위한 나의 시도들은 무엇이 있었지?
  • 개발자 커뮤니티에 질의
  • gpt 사용
  • 멘토가 와서 리뷰

 

• 그 과정에서 나는 무엇을 깨달았고, 어떤 감정/생각이 들었었지?
  • 배달앱에서는 음식을 미리 수량을 수정할 일이 없다
  • 명세서를 더 잘 봐야한다

 

• 이 상태에서 이후 더 나은 내가 되려면 무엇을 보완하지?
  • 명세서 대로 해야 함
  • 확실히 해봐야 생각을 하게 된다.

 

---

 

 

API 설계에도 여러 원칙이 있다.

API의 효율성, 유지보수성, 사용성 및 확장성을 높이는 데 도움을 줍니다.

여기에는 RESTful API 디자인 원칙, API 설계의 모범 사례, 그리고 사용자 경험(UX) 원칙 등이 포함됩니다.

아래는 API 설계 시 고려해야 할 주요 원칙들입니다.

1. 단일 책임 원칙 (Single Responsibility Principle)

• 설명: 각 엔드포인트는 하나의 기능만을 수행해야 합니다. 이를 통해 API의 책임이 명확해지고, 이해와 유지보수가 용이해집니다.
• 예시: 음식 조회, 추가, 수정, 삭제를 각각 다른 엔드포인트로 구분합니다.

2. 일관성 있는 설계 (Consistency)

• 설명: API의 경로, 메서드, 파라미터, 응답 형식이 일관되게 유지되어야 합니다. 이를 통해 API 사용자는 예측 가능한 방식으로 API를 사용할 수 있습니다.
• 예시: 모든 엔드포인트는 /resource 형태를 따르고, GET, POST, PUT, DELETE와 같은 HTTP 메서드를 일관되게 사용합니다.

3. 자원 지향 (Resource-Oriented)

• 설명: API는 자원(resource)을 중심으로 설계되어야 하며, 자원의 상태를 표현하고 조작할 수 있는 메서드를 제공합니다.
• 예시: /api/v1/users에서 사용자 정보를 조회, 생성, 수정, 삭제합니다.

4. RESTful 원칙 (RESTful Principles)

• 설명: RESTful API는 HTTP 메서드를 사용하여 자원을 조작하며, 자원의 URI를 통해 자원을 식별합니다. RESTful 원칙을 따르면 API는 HTTP의 표준을 따릅니다.
• 예시:
  • GET /api/v1/users - 사용자 목록 조회
  • POST /api/v1/users - 사용자 생성
  • GET /api/v1/users/{userId} - 특정 사용자 조회
  • PUT /api/v1/users/{userId} - 특정 사용자 수정
  • DELETE /api/v1/users/{userId} - 특정 사용자 삭제

5. 스테이트리스 (Statelessness)

• 설명: 각 요청은 독립적이어야 하며, 서버는 요청 간의 상태를 유지하지 않아야 합니다. 클라이언트는 필요한 모든 정보를 요청에 포함해야 합니다.
• 예시: 로그인 정보나 상태는 클라이언트에서 관리하고, 서버는 각 요청을 독립적으로 처리합니다.

6. 명확한 오류 처리 (Clear Error Handling)

• 설명: 오류가 발생했을 때 명확하고 일관된 오류 메시지를 반환해야 합니다. 오류 코드와 메시지를 통해 클라이언트가 문제를 이해하고 처리할 수 있어야 합니다.
• 예시:
  • 404 Not Found - 요청한 자원이 존재하지 않음
  • 400 Bad Request - 잘못된 요청 파라미터
  • 500 Internal Server Error - 서버 측 오류

7. 버전 관리 (Versioning)

• 설명: API의 버전을 명확하게 관리하여, API 변경 시 기존 클라이언트가 영향을 받지 않도록 해야 합니다. 버전 관리는 API의 호환성을 보장합니다.
• 예시: /api/v1/resource, /api/v2/resource와 같은 방식으로 버전을 관리합니다.

8. 문서화 (Documentation)

• 설명: API의 사용법, 엔드포인트, 파라미터, 응답 형식 등을 자세히 문서화하여 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 합니다.
• 예시: Swagger/OpenAPI 문서화 도구를 사용하여 API 문서를 자동 생성합니다.

9. 보안 (Security)

• 설명: API는 보안을 고려하여 인증(Authentication)과 권한 부여(Authorization)를 구현해야 합니다. 데이터 보호를 위해 HTTPS를 사용하고, 적절한 권한 검사를 수행해야 합니다.
• 예시: JWT 토큰을 사용하여 인증을 수행하고, HTTPS를 통해 데이터 전송 시 암호화합니다.

10. 성능 최적화 (Performance Optimization)

• 설명: API의 성능을 고려하여 요청과 응답의 지연 시간을 최소화하고, 적절한 캐싱 전략을 사용합니다.
• 예시: 쿼리 결과를 캐싱하거나, ETag와 같은 메커니즘을 사용하여 효율적인 데이터 전송을 구현합니다.

이러한 원칙들을 따르면 API는 더 견고하고, 일관되며, 사용하기 쉬운 구조를 가지게 됩니다. API 설계는 잘 정의된 원칙과 모범 사례를 따르는 것이 중요하며, 이를 통해 API의 효율성과 품질을 높일 수 있습니다.

 

---

 

Patch는 언제 쓰는거지?

언제 PATCH를 사용하는가?

1. 부분 업데이트가 필요할 때: 리소스의 일부만 변경하고자 할 때 PATCH를 사용합니다. 예를 들어, 사용자 프로필에서 이메일 주소나 전화번호만 변경할 때 PATCH를 사용할 수 있습니다.
2. 리소스의 특정 필드만 변경하고 싶을 때: 예를 들어, 주문 상태를 "배달 중"으로 업데이트하는 경우, 전체 주문 정보를 PUT으로 전송하는 대신, PATCH를 사용하여 해당 상태 필드만 수정할 수 있습니다.

단일 책임 원칙과 PATCH

단일 책임 원칙(SRP)은 클래스나 메서드가 하나의 책임만 가지도록 설계하는 원칙입니다. 엔드포인트도 이 원칙을 따를 수 있습니다. 여러 역할을 하는 엔드포인트는 유지보수나 확장성 측면에서 불리할 수 있습니다.

그러나 PATCH 메서드는 단일 책임 원칙을 위반하지 않으며, 적절하게 사용하면 오히려 역할을 명확하게 할 수 있습니다. 예를 들어, 다음과 같은 엔드포인트들이 있을 수 있습니다:

• PATCH /orders/{id}/status: 주문 상태만 변경
• PATCH /users/{id}/email: 이메일 주소만 변경

이처럼 PATCH를 사용하면 각 엔드포인트가 특정 작업만 수행하도록 설계할 수 있습니다.

요약

• PATCH는 리소스의 일부만 업데이트할 때 사용됩니다.
• 단일 책임 원칙에 맞추어 특정 필드나 속성만을 업데이트하는 엔드포인트로 PATCH를 사용하는 것은 클린 코드 작성에 부합합니다.
• 만약 리소스의 전체를 업데이트해야 한다면 PUT을, 특정 부분만 변경해야 한다면 PATCH를 사용하는 것이 좋습니다.

 

PATCH /orders/{id}/status

단일 책임 원칙을 잘 준수

이 경우 엔드포인트가 주문 상태 변경이라는 하나의 명확한 역할

다른 필드를 변경하려는 요청과 명확히 구분

 

1. 명확한 역할 분담: 각 엔드포인트가 특정 작업만을 처리하므로, 코드의 가독성과 유지보수성이 높아집니다.
2. 변경의 범위가 제한됨: PATCH /orders/{id}/status 엔드포인트는 오직 주문의 상태만 변경하므로, 다른 데이터 필드에 대한 변경이 발생하지 않습니다. 이는 예기치 않은 사이드 이펙트를 방지합니다.
3. 확장성: 시간이 지나면서 API가 확장되더라도, 각 엔드포인트가 명확한 책임을 가지고 있으면 새로운 요구사항을 추가하는 것이 더 쉽습니다. 예를 들어, 다른 필드를 수정하는 엔드포인트가 필요할 때, 새로운 엔드포인트를 만들면 됩니다 (PATCH /orders/{id}/delivery-date 등).

따라서 PATCH /orders/{id}/status와 같은 설계는 단일 책임 원칙을 지키면서, 동시에 PATCH 메서드의 유용성을 잘 살린 좋은 접근입니다.