RESTful API 설계에 대한 개인적인 생각 - 1

아래 내용은 개인적인 생각임을 감안해주세요

 

---

2022년 4월 20일 내용 추가
 

원글: https://news.hada.io/topic?id=6121

일관성 유지 : URL/헤더/인증/상태코드..
ISO8601 UTC 날짜 포맷 사용
Public Endpoint만 인증 예외. 나머지는 모두 인증 필수
헬스 체크 Endpoint 제공
API 버저닝
API 키 인증 적용
합리적인 HTTP 상태코드 와 메소드 사용
각 Endpoint에 자체만으로 설명 가능한 간단한 이름을 사용
표준 에러 응답 사용
POST에서 생성된 자원을 리턴
PUT 대신 PATCH
최대한 구체적으로
Pagination 사용
각 자원을 확장 가능하게 (expand 등의 쿼리 파람을 줘서 추가 정보도 리턴 가능하게 설계)

 

원글: https://news.hada.io/topic?id=5823

- "AWS가 15년간 배운 좋은 API를 만드는 6가지 원칙" 에 대한 메모
1. API는 영원하다!
2. 하위 호환성을 지켜주세요.
3. 고객 사용 사례에서 거꾸로 만드세요.
4. 오류가 명시적인 API를 만드세요.
5. 바로 목적과 사용법을 이해할 수 있는 API를 만드세요.
6. 구현 세부 정보는 누출되지 않게 신경을 쓰세요.

- 초기 API 설계에서 실수하는 것
- Smithy를 통한 확장성 높은 API 만들기

---

 

몇년간 엄청나게 많은 API를 개발했는데, 그 중에서 RESTful API 설계에 대한 몇가지 개인적인 생각을 메모로 남겨봅니다.

 - 참고로, 인프라 셋팅/운영, 개발 실무, 개발팀 셋팅 및 SW개발 프로세스 수립, 많은 사용처에게 API 제공 등의 업무를 겪어서 단순 기술적인 부분이 아니라 조직원, 고객(?)에 대한 고민도 일부 반영된 내용입니다.

1. RESTful API를 완벽히 적용하기는 실무에서 어렵습니다.
   1. API 사용쪽에서 방화벽 등의 인프라에 DELETE, PUT이 막혀서 사용이 불가능할 수 있습니다.
   2. 웹 기술에 익숙하지 않는 API 사용자(개발자)가 생각보다 많습니다.(그나마 최근 몇년 사이에 조금 좋아진듯합니다.)
      1. status 200이 정상임을 모르는 경우도 많음.. ;;)
      2. status 200일 경우에만 body를 파싱하도록 개발하는 개발자도 많음
         1. ex) 400응답일때 파라미터 xx가 오류라고 응답하면 에러코드나 설명을 처리할줄 모름
            
            
2. POST와 GET 위주로 사용하는게 좋습니다.
   1. 데이터(리소스) 변경이 발생하는 경우는 POST를 사용
   2. 단순 질의(CQRS패턴의 질의? 같은 느낌인가..)는 GET을 사용
      1. 단, 보안이 중요하면 질의 형태도 POST를 사용
         1. 예) API URL을 메신저에 공유하면 각 메신저 개발사의 봇들이 호출 -> API 개발자가 실수로 인증 기능을 적용 안해둠 -> GET API가 작동->그런데 그 API가 유저 탈퇴 처리하는 운영기능 API였다면???
   3. DELETE와 같은 추가 메소드를 사용하지 못하는 문제는 URL을 잘 정의해서 회피/의도를 노출
      1. 예) URL path 마지막에 의도록 노출(ex. /블라블라/cancel)
         
         
3. 이름을 잘 명명해야합니다.
   1. 이미 한번 배포되어 사용되면 바꾸기가 쉽지 않음
      1. 예)API URL에 오타가 있으면 서비스 종료까지 그대로 사용하게 됨(API 사용자가 생각보다 잘 수정해주지 않습니다.)
         
         
4. API는 일관성을 가져야하며 사용자(API 사용 개발자)가 적용하기 쉬워야합니다.
   
   
5. 지금은 필요하지 않아도 버전을 명시해야 하고 2depth에는 세부 기능의 대표 명사를 사용하는게 좋습니다.
   1. 서비스가 대박이 나서 트래픽이 늘어나면, URL path를 이용해서라도 트래픽을 분산, 또는 MSA로 적용 용이, 달리는 자동차 바뀌 교체 용이
      1. 예) 도메인/v1/member/

 

또 생각나면 추가로 작성하겠습니다.