(22.10.28)HTTP(4) - API 설계 예시

HTTP API - 컬렉션

API 설계 - POST 기반 등록

URI에서는 리소스 자체를 식별해야 한다.

 

리소스에 대한 행위 (조회, 등록, 수정 등)은 URI에 필수적인 것이 아니라는 것이다.

행위는 주로 HTTP 메서드로 구분한다.

 

API 설계 예시

• 상품 목록 /products -> GET
• 상품 등록 /products -> POST
• 상품 조회 /products/{id} -> GET
• 상품 수정 /products/{id} -> PATCH,PUT, POST
• 상품 삭제 /products/{id} -> DELETE

 

POST - 신규 자원 등록 특징

• 클라이언트는 등록될 리소스의 URI를 모른다.
  • 회원 등록 /products -> POST
  • POST /products
• 서버가 새로 등록된 리소스 URI를 생성해준다.
  • HTTP/1.1 201 Created
    Location: /products/100
• 컬렉션(Collection)
  • 서버가 관리하는 리소스 디렉토리
  • 서버가 리소스의 URI를 생성하고 관리
  • 여기서 컬렉션은 /products

 

파일 관리 시스템

API 설계 - PUT 기반 등록

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST 

PUT - 신규 자원 등록 특징

• 클라이언트가 리소스 URI를 알고 있어야 한다.
  • 파일 등록 /files/{filename} -> PUT
  • PUT /files/star.jpg
• 클라이언트가 직접 리소스의 URI를 지정한다.
• 스토어(Store)
  • 클라이언트가 관리하는 리소스 저장소
  • 클라이언트가 리소스의 URI를 알고 관리
  • 여기서 스토어는 /files

 

대부분 POST 기반의 등록 API로 설계한다(컬렉션)

PUT은 거의 비중이 없다.

 

 

HTML FORM 사용

• HTML FORM은 GET, POST만 지원
• AJAX 같은 기술을 사용해서 해결 가능 -> 회원 API 참고
• 여기서는 순수 HTML, HTML FORM 이야기
• 컨트롤 URI
  • GET, POST만 지원하므로 제약이 있음
  • 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
  • POST의 /new, /edit, /delete가 컨트롤 URI
  • HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)
  • 동사를 사용한다

HTML FORM 뿐만 아니라 모든 HTTP 메서드를 사용할 수 있는 경우에도

HTTP 메서드로만 해결하기 어려운 경우가 많기 때문에 실무에서는 컨트롤 URI를 많이쓴다.

 

 

정리

참고하면 좋은 URI 설계 개념

• 문서(document)
  • 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
  •  예) /members/100, /files/star.jpg
• 컬렉션(collection)
  • 서버가 관리하는 리소스 디렉터리
  • 서버가 리소스의 URI를 생성하고 관리
  • 예) /members
• 스토어(store)
  • 클라이언트가 관리하는 자원 저장소
  • 클라이언트가 리소스의 URI를 알고 관리
  • 예) /files
• 컨트롤러(controller), 컨트롤 URI
  • 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
  • 동사를 직접 사용
  • 예) /members/{id}/delete

API 설계 절차

1. /리소스(복수형) 으로 설계한다.

2. 여기에 각종 API에 따라 HTTP 메서드를 활용한다.

3. HTTP 메서드만으로 API 표현이 한계가 있으면 컨트롤 URI를 사용한다.

 

참고: https://restfulapi.net/resource-naming/

 

 

 

 

출처: 인프런, 모든 개발자를 위한 HTTP 웹 기본 지식, 김영한