HTTP API 설계 예시

 

회원 관리 시스템의 API 설계 → POST 기반으로 설계한다면? 

• 회원 목록 /members → GET
• 회원 등록 /members →  POST
• 회원 조회 /members/{id} → GET
• 회원 수정 /members/{id} → PATCH, PUT, POST
• 회원 삭제 /members/{id} → DELETE

앞서 이야기 한 것처럼 URI는 '리소스'만 식별하도록 한다. 행위를 식별하는 것은 최대한 메서드로 구현한다. 

• 회원 목록 : 조회했을 때 필터나 정렬은 쿼리 파라미터로 해주면 됨 → GET 사용
• 회원 등록 : /members에 POST로 넣으면 회원이 등록되는 것으로 설계한다. → POST 사용
• 회원 조회 : URI를 계층 구조로 만들고, 조회 시 /members + 식별자를 쓴다 → GET
• 회원 삭제 : /members + 식별자를 쓴다 → DELTE
• 회원 수정 : 고민이 필요함(Put / Patch / Post)
  → Put은 덮어쓰기다.Patch는 부분수정이다. 기본적으로 데이터 수정은 Patch를 쓰는 것이 좋다. Put으로 데이터를 수정하려면, 회원의 모든 정보를 넣어서 보내야하는데 그러면 낭비기 때문이다. 만약에 Patch가 애매하다면, Post로 수정하는게 좋다.

 

POST - 신규 자원 등록 특징

• 클라이언트는 등록될 리소스의 URI를 모름
  • 회원 등록 /members → POST로 구현. 식별자 넣지 않음. 
  • POST /members 하고 만다. 
• POST로 등록하면, 서버가 새로 등록될 리소스의 URI를 결정한다. 
  • HTTP/1.1 201 Created
  • Location: /members/100
• 컬렉션(Collection) 
  • 컬렉션은 서버가 관리하는 리소스 디렉토리.
  • 컬렉션은 서버가 리소스의 URI를 생성하고 관리한다.
  • 여기서 컬렉션은 /members 임. 

 

파일 관리 시스템의 API 설계, PUT 기반 등록으로 설계한다면? 

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

파일 등록을 할 때는 PUT을 쓴다. PUT을 쓰는 이유는 크게 두 가지가 있다.

• 클라이언트가 업로드 할 파일 이름(URI)를 알고 있기 때문이다.
• 파일은 항상 덮어쓴다. 이와 비슷한 성질은 PUT 메서드다.

 

PUT - 신규 자원 등록할 때 특징

• 클라이언트가 리소스 URI를 결정한다.
  • 파일 등록 /files/{filename} → PUT
  • PUT /files/star.jpg
• 스토어(Store)
  • 클라이언트가 업로드 할 파일의 URI를 관리하는 리소스 저장소
  • 클라이언트가 리소스의 URI을 알고 관리한다.
  • /files는 스토어다.

 

Collection은 POST 메서드로 자료를 관리하는 리소스 저장소며, 이 때 URI는 서버에서 지정을 해준다. 반면 Store는 PUT 메서드로 자료를 관리하는 리소스 저장소이며, URI는 클라이언트가 직접 지정한다. 대부분 Collection 타입의 저장소를 많이 쓴다고 한다. 

 

HTML FORM 사용 (HTTP API 설계)

• HTML FORM은 GET, POST 메서드만 지원함. 
• 이 외의 메서드가 필요할 경우 AJX 같은 기술 사용으로 해결 가능 → 회원 API 참고
• 순수 HTML FORM은 GET, POST만 지원한다. 
• 회원 목록 /members → GET
• 회원 등록 폼 /members/new → GET
• 회원 등록 /members/new , /members → POST
• 회원 조회 /members/{id} → POST
• 회원 수정 폼 /members/{id}/edit → GET
• 회원 수정 /members/{id}/edit, /members/{id} → POST
• 회원 삭제 /members/{id}/delete → POST

위의 정보를 바탕으로 HTTP FORM의 HTTP API 설계를 다시 한번 정리해보겠다.

• 회원 등록 버튼을 누르면 URI 링크를 타고 /members/new로 들어감. 이 링크로 들어가면 회원등록폼이 나옴. 여기 링크로 들어가면 '회원등록폼'이 나옴.
• 회원등록폼에는 '폼태그'가 나오는데, 이곳에 회원 정보가 등록된다. 
• '회원 등록 버튼'을 누르면 '폼태그'에 적힌 정보가 POST로 넘어간다. 이 때는 /member/new, /members 두 개의 URI에서 회원 등록을 선택할 수 있음. 
• /members/new로 하면 회원 등록 폼과 동일한 URI를 사용한다. 메서드 GET, POST를 사용해서 회원 등록폼 조회, 회원 등록을 나누는 것이 가능함. 또 다른 방법으로는 Collection  관리처럼 /members URI에 POST를 넘기는 방법도 가능함.
• 회원 수정 폼 자체를 조회하는 것은 GET이다. 따라서 edit로 들어가더라도 GET으로 회원 수정 폼을 가지고 와야하고, 실제로 회원 수정폼을 가지고 와서 거기에 적힌 데이터를 보내는 시점에 POST를 보내야한다. 
• 회원 삭제는 현재 상태에서는 Delete 라는 메서드를 못 쓰기 때문에 /delete라고 컨트롤 URI를 하나 만들어줘야한다. 

HTTP를 이용한 API를 설계할 때는 가장 기본적으로 1. 리소스 식별을 하기 위해서 API의 URI를 잘 짜둔 후, 2. 행위를 메서드로 식별하는 방법으로 접근한다. 그렇지만 특정한 경우에는 그렇게 대응이 안될 수 있다. 이럴 때는 Control URI라는 것을 만들어 해결한다. Control URI는 URI에 이 객체가 어떤 행위를 할 것인지 잘 알려주는 것을 작성하도록 한다. 

 

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

 

좋은 예시

https://restfulapi.net/resource-naming