HTTP 웹 기본 지식 - HTTP API 설계 예시

HTTP API 설계 예시

HTTP API 설계예시를 살펴보자.

3가지 예시가 있는데,

첫번째는 HTTP API POST 기반으로 등록하는 방법,

두번째는 HTTP API PUT 기반으로 등록하는 방법,

그리고 마지막 세번째는 HTML FORM 을 가지고 사용하는 방법에 대해 알아보자.
참고로 HTML FORM은 GET, POST만 지원한다.

회원 관리 시스템을 만들어야 한다고 가정해보자.

URI는 리소스를 식별해야한다. 리소스가 아닌 다른 것을 식별하면 안된다.

리소스는 "미네랄을 캐다"에서 "미네랄" 자체가 리소스인 것이다.
"캐다"라는 것까지는 리소스가 아닌 것이다.

캐다, 조회하다 등등은 GET, POST, DELETE 같은 HTTP 메서드를 사용하면 된다.

 

POST 기반으로 데이터를 등록하게 되면,
위의 방식으로 URI를 설계하면 된다.

회원 목록을 조회한다 → /members 라고 하면 멤버에 대한 데이터를 json으로 쭉 내려줄 것이다.
그런데 만약에 회원을 검색헀는데  회원이 100만명이면, 특정 회원을 검색할 수 있는 검색어가 들어가야 할 것이다.
검색어를 쿼리 파라미터로 넣도록 설계하면 된다.
혹은, 정렬하고싶으면 정렬 조건도 쿼리 파라미터로 넣도록 설계하면 된다.

회원을 등록한다. → /members에 POST라고 넣으면 된다. /members 같은 것을 "컬렉션"이라고 하는데,
"이 컬렉션에다가(회원을 관리하는 URI에다가) 뭔가 데이터를 넣으면 회원이 새로 등록되게 할 거야!" 라고 서로 약속을 하는 것이다. 그렇게해서 /members에다가 데이터를 넣어주면 회원이 추가로 등록되도록 만든다.

회원을 조회한다. → 회원을 조회하는 것은 회원이라는 /members 컬렉션 아래에다가 URI가 계층 구조로 설계가 되기 때문에 members/에다가 하위에 회원의 id넣어주면 될 것이다. 그런식으로 해서 GET 조회를 한다.

회원을 삭제한다 → 회원 삭제는 /members에다가 지우고싶은게 100번이다 그러면 /100을 넣어서 DELETE를 하면 지워지도록 만든다.

 

회원수정같은 경우는 고민이 조금 필요하다.

이전에 배웠듯이, PUT은 기존것을 완전히 지우고 덮어버리는 것이고, PATCH는 부분적으로 수정할 수 있다.
그래서 회원의 데이터를 수정할 때는 PATCH로 하는 것이 개념적으로 제일 좋다. 그런데, PUT을 쓸 수도 있다.
클라이언트에서 완전히 다 덮어버려도 문제가 없는 상황이라면 PUT을 써도  된다.
그런데,  생각보다 그런게 가능한 상황은 거의 없다.
왜냐면 클라이언트에서 회원 데이터를 전부다 보내야 하기때문이다. 그래야 기존 데이터를 날려버리고 깔끔하게 덮어버릴 수 있다.
만약에 회원데이터중 하나라도 빠지면 그 데이터가 날라가버리는 것이다.

그래서 회원 데이터를 수정할 때는 PATCH를 사용하는 것이 제일 좋다.

PUT은 기존데이터를 완전히 덮을 수 있는 자신이 있을때 쓴다. PUT이 의미가 있을가 있다.
예를 들면, 게시판의 게시글을 수정할때 등이 있다!

그런데 PATCH를 쓰기에도, PUT을 쓰기에도 애매하면 POST를 사용하면 된다.

POST로 신규 자원을 등록할 때의 특징은,

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

 

이번에는 API를 설계하는데 PUT기반으로 설계를 해보자.

예시는 파일 관리 시스템이다.
클라이언트에서 원격지의 파일을 관리할 수 있는 것이다.

그러면 클라이언트가 파일 목록을 조회하려면 → /files를 GET하면 된다.

파일을 조회하려면  → /files에 /{filename}을 GET하면 된다. 그러면 해당 파일 하나만 찝어서 조회할 수 있다.

파일을 등록하려면 → /files에 새로 등록할 파일이름을 클라이언트가 알고 있으므로 PUT을 사용한다.
PUT을 사용하면, /files/{filename}이 있으면 덮어버리고, 없으면 새로생성해서 등록한다.

파일을 삭제하려면 → /files에 /{filename} 을 주고 DELETE를 하면 해당 파일이 삭제된다.

여기서는 PUT으로 파일을 등록하고 있기 때문에, /files의 POST의 의미를 내가 임의로 정할 수 있다.
그래서 POST의 의미를 대량의 파일을 등록한다는 것으로 임의로 지정했다.

POST기반으로 등록할때와 PUT기반으로 등록할 때는 다른점이 있다.

파일이라는 새로운 리소스를 등록할 때,
POST기반등록은 클라이언트가 URI를 알고있지 않아도 되지만,
PUT기반 등록은 클라이언트가 URI를 알고 있어야 한다.

 

PUT으로 신규 자원을 등록하는 것의 특징을 정리해보자.

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

 

• HTML FORM은 GET과 POST만 지원한다.
• AJAX 같은 기술을 사용해서 해결 가능 → 회원 API 참고
• 단, 여기;서는 순수 HTML, HTML FORM 이야기
• GET, POST만 지원하므로 제약이 있음

 

 

HTML FORM이니까 기본적으로 HTML이 그려진다고 생각하자.

회원 목록에 /members GET으로 들어가면  회원목록 HTML이 쭉 나올 것이다.

그러고나서 회원 등록이라는 버튼을 누르면 URI링크가 /members/new 라는 곳으로 들어가게 된다.

그러면 회원 등록 HTML FORM이 나온다. 그러면 회원정보를 FROM 태그를 이용해서 입력해야한다.

그러면 실제 FROM 태그에 회원정보를 입력하고 저장버튼을 누르는데,

FORM Submit 버튼을 누르면 POST로 넘어간다.
그런데 POST로 넘어갈 때, 2가지를 선택할 수 있다.

• 1. 회원 등록 폼을 불러올때 는 /members/new에 GET을 쓰고,
  회원 등록을 할때는 같은 URI /members/new 에 POST를 써서  두가지 URI경로를 맞추는 방법
• 2. FORM을 가지고 올때느 /members/new 로 가져오지만,
  등록할 때는 컬렉션 자원을 관리하는 것처럼 /members에 POST로 넘기는 방법도 있다.

 

1번 방법을 선호해서 사용하면 좋은점은,
Validation 이라는게 있는데,
만약에 /members/new POST로 해서 서버에 던졌는데,
서버에서 뭔가 문제가 있어서 다시 POST의 최종 결과를 회원 등록 FORM으로 다시 보내야 하는 경우가 있다.
그러면 1번방법을써서 두가지 URI경로를 맞춰 놓으면, 경로가 안바뀌고 깔끔하게 해결이 가능하다.

 

회원 조회는 회원목록 HTML에서 회원 목록이 쭉나와있으면 그중에 회원의 조회링크를 누르면 회원상세 HTML로 넘어갈 것이다.

회원 상세 HTML에서 수정 버튼이 있다고 생각해보자.
수정하기를 누르면, HTML 수정 폼으로 이동해야 해서 회원 수정 폼도 하나의 리소스라고 보고, /members/{id}/edit 로 간다. 그런데, FORM 자체를 보는 것은 어떠한 변경이 일어나는 것이 아니라, 수정한 FORM을 실제로 서버에 보낼때 변경이 일어나는 것이기 때문에 회원수정 폼을 보는 것은 GET을 사용한다.

회원 수정 FORM의 데이터를 내가 변경을 해서 회원 수정 버튼을 누르면, HTML FORM 데이터가 서버로 전송이 되어야 한다. 그때 URI 경로에 대해서 고민을 해야하는데, 그때도 회원 등록과 마찬가지로 고민을 해야한다.

• /members/{id}/edit로 POST를하거나,
• /members/{id} 로  POST를 하거나

두가지중에 선택해야 한다.

이때에도 수정 form의 URI와 수정 URI를 맞추는 것을 선호한다.

 

회원 삭제 같은 경우에는,
만약에 DELETE 메서드를 사용할 수 있으면, /members/{id}에 DELETE로 넘기면 되겠지만,
HTML FORM에서는 GET, POST만 허용된다.
그럴때는 어쩔수 없이 /members/{id}/delete라고 컨트롤 URI를 사용해야 한다. 그리고 POST로 쓴다.

• HTML FORM은 GET, POST만 지원한다.
• 그래서 컨트롤 URI라는 것을 사용한다.
  
  • GET, POST만 지원하므로 제약이 있음
  • 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
  • POST의 /new, /edit/, /delete가 컨트롤 URI
  • HTTP 메서드로 해결하기 애매한 경우 사용 (HTTP API 포함, HTTP API에서도 HTTP 메서드로 깔끔하게 안떨어지는 경우가 많이 있기 때문)

 

• HTTP API - 컬렉션 스타일
  • POST 기반 등록
  • 서버가 리소스 URI 결정
• HTTP API - 스토어 스타일
  • PUT 기반 등록
  • 클라이언트가 리소스 URI 결정
• HTML FORM 사용
  • 순수 HTML + HTML FORM 사용
  • GET, POST만 지원함. 필요에 따라 컨트롤 URI를 사용하기도 함.

 

 

참고하면 좋은 URI 설계 개념에 대해 짚고 넘어가도록 하자.
정답은 아니고, 좋은 Practice라고 이해하자.

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