URI 설계

URI 설계

리소스(= Reprensntation) 식별이 URI 설계에서 가장 중요하다.

예를들어, 회원을 등록하고 수정하고 조회하는 경우에 회원 이 리소스이며, URI에 매핑해야한다.

리소스에 대한 행위는 HTTP Method를 통해서 표현해야 한다.

예를들어, 회원을 등록하고 수정하고 조회하는 위의 예에서, 등록, 수정, 조회는 HTTP Method를 통해 표현

리소스를 식별하고, URI 계층 구조를 활용!

URI 설계 참고 사항

• 복수로 표현
  • 리소스는 컬랙션과 단일일 수 있음
  • 컬렉션
    • /customers
  • 단일
    • /customers/{id}
• 컬렉션과 서브 컬렉션
  • 서브 컬렉션
    • /customers/{customerId}/accounts
  • 서브 컬렉션 단일
    • /customers/{customerId}/accounts/{accountId}
• URI Naming Convention and Best Practices
  • 리소스를 명사로 표현
  • / 을 사용하여 계층 관계 표현
  • URI 마지막에 / 을 붙이지 말라
  • URI 가독성을 위해 - (hyphen) 사용
  • _ (underscore) 사용하지 말라
  • 소문자 사용
  • 파일 확장자를 사용하지 말라
  • 절대 CRUD 함수 이름을 URI에 쓰지 말라
  • 별도의 새로운 API 대신 query component 를 사용하여 URI 컬렉션을 필터링(정렬, 페이징 등)하라
  • 동사를 쓰지 말라

HTTP Method

종류

• GET
  • 리소스 조회
  • 리소스 변경이 발생하는 곳에 사용 X
• POST
  • 요청 데이터 처리, 주로 등록에 사용
• PUT
  • 리소스를 대체, 해당 리소스가 없으면 생성
  • 실제 리소스 수정에 적합하지 않음
• PATCH
  • 리소스 부분 변경
• DELETE
  • 리소스 삭제
  • 삭제에 대해 hard delete(실제 삭제)와 soft delete(데이터는 남긴 채 삭제 표기하고 클라이언트에 삭제로 인지시키기)로 내부 정책에 따라 결정
• HEAD
  • GET과 동일하나 메시지 부분을 제외하고 상태 줄과 헤더만 반환
• OPTIONS
  • 대상 리소스에 대한 통신 가능 옵션을 주로 설명. 주로 CORS에서 사용
• CONNECT
  • 대상 자원으로 식별되는 서버에 대한 터널을 설정
• TRACE
  • 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트 수행

속성

Safe

호출해도 리소스를 변경하지 않음

해당하는 HTTP Method : GET, HEAD, OPTIONS, TRACE

Idempotent

몇 번을 호출하든 결과가 동일함을 의미(멱등)

외부 요인으로 중간에 변경되는 것까지는 고려하지 않음

멱등은 왜 필요한가?

-> 서버가 TIMEOUT 등으로 정상 응답을 못주었을때, ‘클라이언트가 같은 요청을 다시 해도 되는가?’ 판단의 근거가 됨.

예를들어, 클라이언트가 리소스를 삭제하려고 요청하였을때, 서버에서 응답 메시지가 반환되지 않아 클라이언트가 자동으로 DELETE 요청을 재 요청시, 해당 method가 멱등이라 괜찮음

해당하는 HTTP Method : GET, HEAD, PUT, DELETE, OPTIONS, TRACE

Cacheable

응답 결과 리소스를 캐시해서 사용

해당하는 HTTP Method : GET, HEAD, POST, PATCH가 가능하지만, 실제로는 구현의 어려움으로 GET, HEAD정도만 cache 사용

(참고) URL 문법

scheme://[userinfo@]host:[:port][/path][?query][#fragment]

ex) https://www.google.com:443/search?q=hello&hl=ko

• Protocol(scheme) : https
  • 어떤 방식으로 리소스에 접근할 것인가 정하는 규칙
• Host : www.google.com
  • 도메인명이나 IP 주소 직접 사용가능
• Port : 443
  • 접속 포트
• Path : /search
  • 리소스 경로로 계층적 구조
• Query Parameters : q=hello&hl=ko
  • query string으로도 불림
• fragment
  • html 내부 북마크 등에 사용. 서버에 전송하는 정보가 아님

참고

• REST API URI Naming Conventions and Best Practices
• 모든 개발자를 위한 HTTP 웹 기본 지식, 김영한, inflearn