개발일기
HTTP API 설계 예시 본문
- HTTP API - 컬렉션
- POST 기반 등록
- 예) 회원 관리 API 제공
- HTTP API - 스토어
- PUT 기반 등록
- 예) 정적 컨텐츠 관리, 원격 파일 관리
- HTML FORM 사용
- 웹 페이지 회원 관리
- GET, POST만 지원
HTTP API를 통해서 데이터를 등록하는데 API를 어떻게 써야하는지 알아야 한다. 첫번째 POST기반으로 데이터를 등록하는 기능 여기서 우리는 POST도 DATA를 등록할 때 사용할 수 있고, PUT도 데이터를 등록할 때 사용할 수 있다는 것을 배웠다.
이 두개를 활용할 때 약간 다른 특징이 있다.
회원 관리 시스템
API 설계 - POST 기반 등록
- 회원 목록 /members -> GET
- 회원 등록 /members -> POST
- 회원 조회 /members/{id} -> GET
- 회원 수정 /members/{id} -> PATCH, PUT,POST
- 회원 삭제 /members/{id} -> DELETE
제일먼저 회원 기능을 설계해야한다고 생각해보자.
리소스만 가지고 URL을 설계해야함. ex) 미네랄을 캐다. (여기에서 미네랄이 리소스이고 캐다는 리소스가 아님)
캐다 같은 동사들은 GET, POST 이런것들로 설계해야한다.
- 회원 목록은 /members를 하면 member에대한 데이터를 내려준다. 검색어가 필요하면 queryParameter에 넣도록 설계하면 된다.
- 회원 등록은 /members에 POST라고 해주면 된다. /members같은 것을 우리는 컬렉션이라고 한다. 회원 관련 URI에다가 회원 관련된 데이터를 넘겨주면 회원을 등록하게 해준다는 의미이다.
URI가 계층구조로 설계 되기 때문에 아래와 같이 만들면 사람이 이해하기 굉장히 쉽다.
- 회원 조회 /members/{id} -> GET
위에와 같이 회원 하나를 조회하는 단건 조회를 설계하면 된다.
- 회원 삭제 /members/{id} -> DELETE id값을 받으면 그냥 해당 ID삭제
- 회원 수정 /members/{id} -> PATCH (부분적으로 수정가능) , PUT(아예 새롭게 만듬), POST
먼가 회원의 데이터를 수정할 때는 PATCH를 사용하는게 좋음 완전히 새로 덮어 씌워야하면 PUT을 사용해도 됨.
PATCH를 사용하는게 굉장히 좋음.
PUT이 의미가 있는 경우 게시판을 수정할 때, 게시글을 수정할 때는 완전히 덮어 씌워도됨.
그 다음에 이것도 저것도 애매하면 POST를 사용하면 됨.
회원 관리 시스템 POST - 신규 자원 등록 특징
- 클라이언트는 등록될 리소스의 URI를 모른다.
- 회원 등록 /members -> POST
- POST /members
- 서버가 새로 등록된 리소스 URI를 생성해준다.
- HTTP/1.1 201 Created
- Location :/members/100
- 컬렉션(Collection)
- 서버가 관리하는 리소스 디렉토리
- 서버가 리소스의 URI를 생성하고 관리
- 여기서 컬렉션은 /members
클라이언트가 리소스를 등록한다. 회원 등록할 때, /members 에 POST라고 보낸다.
POST로 데이터 등록할 때는 서버에서 데이터를 만들고 리소스 URI를 만들어준다.
서버가 관리하는 것을 컬렉션이라고한다.
파일 관리 시스템 API 설계 - PUT 기반 등록
- 파일 목록 /files -> GET
- 파일 조회 /files/{filename} -> GET
- 파일 등록 /files/{filename} -> PUT
- 파일 삭제 /files/{filename} -> DELETE
- 파일 대량 등록 /files -> POST
원격지에 파일을 관리하는 시스템 파일 목록을 조회하려면 파일목록이니깐 /fiies 라고 하고 GET하면 file들이 전부다 나온다.
파일 조회 /files/{filename}이라고 하면 파일네임을 찍어서 파일하나만 조회할 수 있음.
파일 등록할 때, PUT을 사용한다. 없으면 새로 생성 있으면 기존꺼 덮고 새로 생성 이 경우에는 PUT딱 어울림.
파일 하나 삭제할때, 파일네임하면 파일하나 삭제
/files 대량의 파일 등록 다른 경로로 사용하여도 상관없음.
파일 관리 시스템 PUT - 신규 자원 등록 특징
- 클라이언트가 리소스 URI를 알고 있어야 한다.
- 파일 등록 /files/{filename} -> PUT
- PUT /files/star.jpg
- 클라이언트가 직접 리소스의 URI를 지정한다.
- 스토어(Store)
- 클라이언트가 관리하는 리소스 저장소
- 클라이언트가 리소스의 URI를 알고 관리
- 여기서 스토어는 /files
PUT가지고 자원을 넣으면 클라이언트가 리소스 URI 를 알고 있어야함 /files/{filename}의 파일네임을 넣어주어야함.
클라이언트가 등록된 URI를 다알고 있어야함.
PUT은 사용비중이 많지않음 실제 실무에서는 POST기반의 컬렉션을 대부분 사용한다.
HTML FORM 사용
- HTML FORM은 GET, POST만 지원
- AJAX같은 기술을 사용해서 해결 가능 -> 회원 API 참고
- 여기서는 순수 HTML, HTML FORM 이야기
- GET, POST만 지원하므로 제약이 있음
- 회원 목록 /members -> GET
- 회원 등록 폼 /members/new -> GET
- 회원 등록 /members/new, /members -> POST
- 회원 조회 /members/{id} -> GET
- 회원 수정 폼 /members/{id}/edit -> GET
- 회원 수정 /members/{id}/edit, /members/{id} -> POST
- 회원 삭제 /members/{id}/delete -> POST
- 회원 목록에 들어온다. 그러면 회원 목록이 HTML에 쭉나온다.
- 먼저 회원등록이라는 버튼을 누른다 URI 링크가 /members/new라는 링크로 들어간다.
회원 등록 폼이 나온다. 폼태그가 있고 폼정보들이 들어올 것이다. 그러면 여기서 실제 폼태그의 정보를 입력한 다음에 저장 버튼을 누른다.
폼 submit버튼을 누른다. 그러면 여기서 POST로 넘어간다.
폼을 넘어갈 때, 두가지 URL을 선택할 수 있음. /members/new , /members의 POST로 두가지 URI로 넘겨줄 수 있음.
둘중에 하나를 선택하면 된다.
개인적으로 김영한 강사님이 선호하는 스타일은 1:1 매칭을 시키는 것을 선호한다.
/members/new이런식으로 하는 것을 선호함. 왜냐하면 가끔씩 서버에 문제가 생겨서 다시 회원등록 폼으로 넘겨야 하는 경우가 있음. 그러면 이렇게 둘이 맞춰놓으면 경로가 안바뀌고 깔끔하게 해결됨. 이렇게 하는 방식을 개인적으로 추천한다고 하심.
회원 조회는 회원 목록이 쭉나오는데 링크하나를 누른다. html에서 링크를 누르면 회원 상세화면으로 이동한다.
여기서 회원 상세화면에서 수정버튼이 있어서 수정하기를 누르면 회원 수정 폼으로 이동해야 한다.
회원 수정 폼도 하나의 리소스로 본다음에 /members/{id}/edit 의 회원 수정폼으로 이동한다.
폼 자체를 보는 것은 변경이 일어나는 것이 아니다. 이때도 GET을 쓴다.
그다음에 변경을 해서 회원 수정에서 수정 버튼을 누르면 그러면 HTML 폼데이터가 서버로 전송이 되어야 한다.
그때 URL 경로에대해서 고민을 해야한다.
/members/{id}/edit , /members/{id} -> POST
폼의 URL과 수정의 URL을 맞추는 것을 추천
회원 삭제같은 경우에는 /members/{id}/delete -> POST delete라는 메서드가 없어서 어쩔수없이 /delete로해서 컨트롤 URI를 사용해야 한다.
HTML FORM 사용
- HTML FORM은 GET, POST만 지원
- 컨트롤 URI
- GET, POST만 지원하므로 제약이 있음
- 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
- POST의 /new, /edit, /delete가 컨트롤 URI
- HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)
실무에서는 컨트롤 URI를 많이씀. 컨트롤 URI를 무식하게 사용하면 안됨
컨트롤 URI를 최대한 사용하고 안되면 대체제로 사용한다.
HTTP ID로 안떨어지는 경우가 많음 어쩔수없이 컨트롤 URI 사용할 때가 많음.
정리
- HTTP API - 컬렉션
- POST 기반 등록
- 서버가 리소스 URI 결정
- HTTP API - 스토어
- PUT 기반 등록
- 클라이언트가 리소스 URI 결정
- HTML FORM 사용
- 순수 HTML + HTML form 사용
- GET, POST만 지원
정리 참고하면 좋은 URI 설계 개념
- 문서(document)
- 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
- 예)/members/100, /files/star.jpg
- 컬렉션(collection)
- 서버가 관리하는 리소스 디렉터리
- 서버가 리소스의 URI를 생성하고 관리
- 예) /members
- 스토어(store)
- 클라이언트가 관리하는 자원 저장소
- 클라이언트가 리소스의 URI를 알고 정리
- 예) /files
- 컨트롤러(controller), 컨트롤 URI
- 문서, 컬렉션, 스토어로 해결하기 여려운 추가 프로세스 실행
- 동사를 직접 사용
- 예) /members/{id}/delete
개발할 때 대부분 컬렉션 스타일을 사용할 것이다.
이런식으로 현업에서 왠만해서 깔끔하게 떨어지지 않는다. 그래서 4번째 개념인 컨트롤러 URI가 꼭 필요하다.
'Spring > (김영한님)HTTP웹 기본 지식' 카테고리의 다른 글
| 2xxx - 성공 (0) | 2023.03.15 |
|---|---|
| HTTP 메서드 활용 (클라이언트에서 서버로 데이터 전송) (0) | 2023.03.10 |
| HTTP 메서드의 속성 (0) | 2023.03.10 |
| HTTP 메서드 - PUT, PATCH, DELETE (0) | 2023.03.10 |
| HTTP 메서드 - GET, POST (0) | 2023.03.10 |