[HTTP] HTTP 메서드 활용 - HTTP API 설계 예시

HTTP 메서드 활용

HTTP API 설계 예시

• HTTP API - 컬렉션

  • POST 기반 등록

  • 예) 회원 관리용 API 제공하는 상황이라고 가정

• HTTP API - 스토어

  • PUT 기반 등록

  • 예) 정적 컨텐츠 관리, 원격 파일 관리

    • PUT과 POST 모두 데이터를 등록할 때 사용할 수 있지만, 약간 다른 특징이 존재한다

      • PUT과 POST의 각각의 특징에 대해서 아래서 다룰 것이다.

• HTML FORM 사용

  • 웹 페이지 회원 관리

  • GET, POST만 지원

회원 관리 시스템

API 설계 - POST 기반 등록

• 회원 목록 /members -> GET

  • 정렬 등의 검색 옵션이 필요하면 query parameter를 사용하자

• 회원 등록 /members -> POST

  • 컬렉션에, 회원을 관리하는 uri(/members)에 데이터를 넣으면 회원이 새로 등록되게 하도록 약속을 한다.

• 회원 조회 /members/{id} -> GET

• 회원 수정 /members/{id} -> PATCH, PUT, POST

  • 회원의 데이터를 수정할 때는 PATCH를 사용하는 것이 개념적으로는 제일 좋다

  • PUT의 경우 데이터를 완전히 덮어써도 되는 경우 사용해도 된다

    • 회원 데이터를 전부 전송해야 하기 때문에 전송해야 할 데이터가 많음
    • ex) 게시글을 수정하는 경우

  • 애매한 경우 POST

• 회원 삭제 /members/{id} -> DELETE

POST - 신규 자원 등록 특징

• 클라이언트는 등록될 리소스의 URI를 모른다.

  • 회원 등록 /members -> POST

  • POST /members

    • ID(식별자)가 10일지, 100일지, 50일지.. 클라이언트는 알 수 없다

• 서버가 새로 등록된 리소스 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

  • /files에 있는 POST의 의미를 내가 임의로 정할 수 있다.

  • 여기서는 임의로 대량의 파일을 등록하는 것으로 지정을 했다.

  • 다른 경로를 사용해도 됨

PUT - 신규 자원 등록 특징

• 회원 관리 시스템과 다르게 파일 관리 시스템에서 파일을 등록하는데 POST가 아닌 PUT을 사용하고 있다.

• 클라이언트가 리소스 URI를 알고 있어야 한다.

  • 파일 등록 /files/{filename} -> PUT

  • PUT /files/star.jpg

• 클라이언트가 직접 리소스의 URI를 지정한다.

  • 이 말은 즉, 클라이언트가 생성될 리소스의 URI를 본인이 다 알고 본인이 관리한다는 것이다.

  • POST의 경우에는 /members로 끝냈다. 몇 번인지 알려주지 않았음

    • POST의 경우 등록할 데이터를 넘기면 서버가 알아서 회원의 ID를 만들고 이 리소스 URI에 대한 경로도 서버에서 판단해서 만든 후 클라이언트에 내려준다

    • POST로 신규 데이터를 등록하는 것은 클라이언트가 서버에게 요청하는 것이다

  • 반면에 PUT 기반으로 등록을 할 때는 리소스 URL을 미리 다 알고 등록을 해야 하기 때문에, 클라이언트가 등록될 리소스의 URL을 직접 다 관리한다

    • 이러한 스타일의 관리를 스토어라고 한다

• 스토어(Store)

  • 클라이언트가 관리하는 리소스 저장소

  • 클라이언트가 리소스의 URI를 알고 관리

  • 여기서 스토어는 /files

중간 요약

• API 설계할 때 두 가지로 크게 분류할 수 있다.

  • POST 기반 등록

    • Collection

  • PUT 기반 등록

    • Store

• 대부분 POST 기반의 Collection을 사용한다

HTML FORM 사용

• HTML FORM은 GET, POST만 지원

  • AJAX 같은 기술을 사용해서 해결 가능 -> 회원 API 참고

• 여기서는 순수 HTML, HTML FORM만 가지고 이야기한다.

• GET, POST만 지원하므로 제약이 있음

---

• 회원 목록 /members -> GET

• 회원 등록 폼 /members/new -> GET

• 회원 등록 /members/new, /members -> POST

1. 회원 등록 버튼을 누른다
2. /members/new 로 URI 링크가 들어간다
3. 폼에 데이터를 입력한다음 저장 버튼(form submit) 버튼을 누른다
4. POST로 메시지가 전송된다. 이 때 두 가지를 선택할 수 있다.
   1. 폼을 불러 올 때는 /members/new에 GET으로, 회원을 등록할 때는 /members/new에 POST로 (두 가지 URL 경로를 맞추는 스타일)
   2. 폼을 불러 올 때는 /members/new에 GET으로, 회원을 등록할 때는 /members에 POST로(마치 컬렉션 자원을 관리하는 것같은 스타일)
   3. 강사님은 1번을 선호한답니다. (validation 과정에서 포스트 결과를 form으로 다시 보낼 때 같은 URI로 보내면 깔끔해짐. 경로가 이동하면 폼으로 다시 돌아가지 못함)

• 회원 조회 /members/{id} -> GET

• 회원 수정 폼 /members/{id}/edit -> GET

1. 회원 조회를 통해서 회원 상세 html이 나온다.
2. 수정하기 버튼을 누른다
3. 수정 폼도 하나의 새로운 리소스로 보고 /members/{id}/edit로 간다. 이 때 폼 자체를 보는 것은 변경이 일어나는 것은 아니기 때문에 get을 사용한다

• 회원 수정 /members/{id}/edit, /members/{id} -> POST

1. 폼의 데이터를 내가 다 변경해서 수정 버튼을 누르면 HTML 폼 데이터가 서브로 전송이 돼야 한다.
2. 이 때, URL 경로는 /members/{id}/edit, /members/{id} 두 가지 중에서 선택한다. (Form의 url과 맞출 것인지 안 맞출 것인지 선택!)

• 회원 삭제 /members/{id}/delete -> POST

  • DELETE 메서드를 사용하지 못하기 때문에 어쩔 수 없이 /delete라는 컨트롤 URI를 사용해야 한다

---

• HTML FORM은 GET, POST만 지원

• 컨트롤 URI

  • GET, POST만 지원하므로 제약이 있음

  • 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용

  • POST의 /new, /edit, /delete가 컨트롤 URI

  • HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)

    • 실무에서 컨트롤 URI를 진짜 많이 사용한다고 함. 물론 최대한 리소스를 가지고 URI를 설계하는게 우선임!

      • 실무에서 HTTP API의 GET POST DELETE PUT 등의 메서드들로 깔끔하게 적용이 되지 않는 경우가 많아 컨트롤 URI를 많이 필요로 한다.

정리

• HTTP API - 컬렉션

  • POST 기반 등록

  • 서버가 리소스 URI 결정

• HTTP API - 스토어

  • PUT 기반 등록

  • 클라이언트가 리소스 URI 결정

• HTML FORM 사용

  • 순수 HTML + HTML form 사용

  • GET, POST만 지원

TIP) 참고하면 좋은 URI 설계 개념

• 문서(document)

  • 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)

  • 예) /members/100, /files/star.jpg

• 컬렉션(collection)

  • 서버가 관리하는 리소스 디렉터리

  • 서버가 리소스의 URI를 생성하고 관리

  • 예) /members

• 스토어(store)

  • 클라이언트가 관리하는 자원 저장소

  • 클라이언트가 리소스의 URI를 알고 관리

  • 예) /files

    • 대부분 컬렉션을 쓰고, 파일 시스템이나 일부 게시판 정도에는 스토어를 사용하는게 좋을 수 있다.

• 컨트롤러(controller), 컨트롤 URI

  • 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행

  • 동사를 직접 사용

  • 예) /members/{id}/delete

1. 일단 먼저 리소스로 설계! (/members, /orders, /orders/orderid)
2. 1번으로 해결이 안되면 컨트롤 URI를 사용해라

https://restfulapi.net/resource-naming

Ref) 모든 개발자를 위한 HTTP 웹 기본 지식 - 인프런, 김영한 강의