3월 9일 HTTP API 설계 예시

HTTP API - 컬렉션

-post 기반 등록 

ex)회원 관리 API 제공

 

HTTP API - 스토어

-put 기반등록 

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

 

HTTP FORM 사용

웹페이지 회원관리 , GET , POST만 지원

 

post와 put은 기능에 차이가 있다.

 

회원관리 시스템 , API 설계 , POST 기반 등록

회원 목록 /members -> get (조회) get은 해당 리소스의 목록을 가져온다.

회원 등록 /members -> post (등록) post는 해당 리소스의 위치에 값을  추가한다.

회원 조회 /members/{id} ->GET get이 리소스/컬렉션에 값을 가져온다.

회원 수정 /members/{id} -> patch , put , post

회원 삭제 /members/{id} -> delete delete는 리소스/컬렉션의 값을 삭제한다.

/members 가 리소스.

 

API는 리소스를 식별해야한다 , 메소드로 행동을 나눈다.

/members 를 컬렉션(리소스)이라 한다.

 

수정 , put , patch, post

put은 덮어쓰기 , patch는 부분적 수정 

원래 patch는 수정에 쓰는게 일반적이지만 put으로 완전히 덮을 수도 있다.

또한 put은 게시판에 게시글을 완전히 수정하는데 사용한다.

애매한경우 post를 사용한다.

 

post - 신규 지원등록 특징

클라이언트는 등록될 리소스의 URI를 모른다.(서버가 리소스를 생성해서 URI를 만들어서 반환한다,)

-회원등록 /members -> post

-post /members

 

서버가 새로 등록된 리소스 URI를 생성해준다

-HTTP/1.1 2-1 created

location : /members/100  응답에 포함된 uri 주소

 

컬렉션(collection)

서버가 관리하는 리소스 디렉토리 ex)/members/100

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

서버가 리소스 데이터를 관리한다.

여기서 컬렉션은 /members

 

post는 등록된 데이터의 리소스 /members/100에 100부분을 서버가 생성하게된다.

그래서 응답받을때 location /members/100 이라는

생성된 리소스의 위치값을 받을 수 있다.

 

 

파일관리 시스템 , API 설계 , PUT 기반 등록(원격지에 파일관리 시스템이 있는경우)

 

파일목록 /files -> get /files 전체를 조회

파일조회 /filse/{filename} -> get /하나의 값만 조회

파일등록 /files/{filename} -> put /새로 등록할 위치에 파일등록

파일삭제 /files/{filename} -> delete /파일하나 삭제

파일 대량 등록 /files -> post

 

클라이언트가 등록할 위치를 지정

 

put-신규 자원등록 특징

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

클라이언트가 위치를 지정한다, 클라이언트가 위치를 알고있다.

-파일등록 /files/{filename} -> put

-put/files/start.jpg

 

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

클라이언트가 리소스를 관리한다.

 

스토어(store)

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

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

여기서 스토어는 /files

 

put 클라이언트가 리소스 관리 , 이 리소스를 store라 한다.

post 서버가 리소스를 관리 , 이 리소스를 collection이라 한다.

 

대부분 post , collection을 사용한다.

 

HTML FORM 사용

HTML FORM은 GET , POST 만 지원

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

여기서는 순수 HTML , HTML FORM의 이야기.

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

 

설계 (FORM)

 

회원목록 /members -> get

회원등록폼 /members/new -> get (submit 제출)

회원등록 /members/{id} -> get

회원수정폼 /members/{id}/edit -> get (조회로 취급)

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

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

 

post일 경우 URI를 고려해야 한다.

delete의 겨웅는 URI를 따로 만들고 POST로 넘긴다.

컨트롤 URI

FORM 은 GET , POST만 지원하기 때문에 사용에 제약이 있다.

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

POST의 /new /edit /delete 가 컨트롤 URI(post로 넘긴다)

 

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

 

컨트롤 URI는 가급적 리소스(post)로 해결해보고 불가능할때 대체제로 사용해야한다,

HTTP API 에서도 컨트롤 URI(동사) 를 사용할 경우가 있다.

 

정리

HTTP API - 컬렉션

-post 기반 등록

-서버가 리소스 URI를 결정

-이를 컬렉션이라 한다.

 

HTTP API - 스토어

-put 기반 등록

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

-이를 스토어라 한다.

 

HTML FORM 사용

순수 HTML + HTML form 사용

get , post만 지원

컨트롤 URI 사용

 

참고하면 좋은 URI 설계 개념

 

문서(document) (제일 작은 개념)

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

ex) /members/100 , /files.star.jpg

 

컬렉션(collection(post)(서버))

서버가관리하는 리소스 디렉토리

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

ex) /members

 

스토어(store(put)(클라이언트))

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

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

ex) /files

 

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

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

동사를 직접 사용

ex) /members/{id}/delete

 

/members/{id} 여기까지에서 해결이 안되는 상황에는

controller URI를 사용해서 /members/{id}/delete를 사용한다.

 

1.collection과 document로 최대한 해결한다.

2.안되면 controller를 사용한다.