Restful API Design

• 기본적으로 디자인을 잘할려면 → 여러 API문서를 보면서 많이 따라 해보는것이 좋다.

  • 글로벌 서비스의 REST API 문서를 참조하는 것은 좋은 습관!
  • 참고할 사이트들

• REST API 설계의 정답은 없음

  • 회사, 조직의 설계 정책을 잘 따라 설계 해야한다.

• 일관 된 설계 정책이 중요

  • url, json field 등 협업자 끼리 일관되게 설정하는것이 좋다.

API의 기본설명

• API가 어떤 동작을 하고 무엇을 위해 사용하는지 정리

• Notion, Swagger, Spring Rest Docs .. 등 여러 Tool 존재

• 관련 문서 작성 팁

  Spring Rest Docs 적용 | 우아한형제들 기술블로그

  • Spring Rest Docs는 테스트 코드도 자동으로 작성된다고 한다.

Request 파라미터

• 필수 파라미터와 선택 파라미터를 구분한다.
  • 모든 파라미터를 필수로 해버리면 수정 및 사용이 어려울수도 있음
• 타입 및 간단한 설명 추가한다. (이름이 명확하다면 설명 필요 없을 수 있음)
• 예시 데이터를 제공한다. (Optional)

→ 사실 어찌 되었던, 정보가 풍부하면 좋음

HTTP API 설계 팁

• 동사보다는 명사(리소스)를 위주로 작성하되 이는 필수가 아니다!