[Spring Rest API] REST API 설계 규칙 - 1

 

규칙

• Rule1: 도큐먼트 이름으로는 단수 명사를 사용하여야 한다
• Rule2: 컬렉션 이름으로는 복수 명사를 사용하여야 한다.
• Rule3: 스토어 이름으로는 복수 명사를 사용하여야 한다.
• Rule4: 컨트롤러 이름으로는 동사나 동사구를 사용해야 한다.
• Rule5: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
• Rule6: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.
• Rule7: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
• Rule8: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 한다.

메소드 규칙

• CRUD 기능을 나타내는 것은 URI에 사용하지 않는다
• PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다.
• PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.
• POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다.
• POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다.
• DELETE 메서드는 그 부모로부터 리소스를 삭제하는데 사용해야 한다.

리소스 원형(Document, Collection, Store, Controller)

도큐먼트

도큐먼트 도큐먼트 리소스는 객체 인스턴스나 데이터베이스 레코드와 유사한 단일 개념이다. 일반적으로 도큐먼트의 상태 표현은 값을 가진 필드와 다른 관련 리소스와의 링크 둘 다를 가지게 된다. 기본적인 필드와 링크 기반 구조로 인해, 도큐먼트 타입 은 다른 리소스 원형들의 기반 원형이 된다. 즉, 서로 다른 리소스 원형 세 개는 도 큐먼트 원형에서 분리된 것이라 볼 수 있다. 다음 URI는 각각 도큐먼트 리소스를 나타낸다.

http://api.hanzari.restapi.org/api/buildings/building1 
http://api.hanzari.restapi.org/api/buildings/building1/floors/5F 
http://api.hanzari.restapi.org/api/buildings/building1/floors/5F/seats/5-62 

도큐먼트 리소스는 자식 리소스를 가질 수 있는데, 이 자식 리소스는 특정한 종속 개념을 표현한다. 단일 부모 하나는 여러 가지 다른 리소스 타입을 가질 수 있어서, 논리적으로 도큐먼트는 docroot로 알려진 REST API 루트 리소스 후보에 해당한 다. 다음 예로 든 URI는 docroot를 나타내는데, Hanzari REST API의 공개된 진입점entry point을 의미한다.

 http://api.hanzari.restapi.org 

컬렉션

컬렉션 리소스는 서버에서 관리하는 디렉터리라는 리소스다. 클라이언트는 새로 운 리소스를 제안해서 컬렉션에 포함시킬 수 있다. 그러나 새로운 리소스를 생성할 지는 컬렉션에 달려 있다. 컬렉션 리소스에 포함하고 싶은 것을 선택하고, 포함된 각 리소스의 URI를 결정한다. 다음의 각 URI는 컬렉션 리소스를 나타낸다.

http://api.hanzari.restapi.org/buildings
http://api.hanzari.restapi.org/buildings/building1/floors 
http://api.hanzari.restapi.org/buildings/building1/floors/5F/seats

스토어

스토어는 클라이언트에서 관리하는 리소스 저장소다. 스토어 리소스는 API 클라 이언트가 리소스를 넣거나 빼는 것, 지우는 것에 관여한다. 스토어 스스로 새로운 리소스를 생성하지 못하기 때문에, 새로운 URI를 만들지는 못한다. 대신 리소스는 스토어에 처음 저장될 때, 클라이언트가 선택한 URI를 가진다. 다음은 클라이언트 프로그램에서 employeeID가 M12451인 사용자를 보여주고, 가상의 Hanzari REST API를 사용 하여 seats라는 스토어에 5-63라는 도큐먼트 리소스를 넣는 예다.

PUT /employees/M12451/seats/5-63

컨트롤러

컨트롤러 리소스는 절차적인 개념을 모델화한 것이다. 컨트롤러 리소스는 실행 가 능한 함수와 같아서 파라미터(입력 값)와 반환 값(출력 값)이 있다. 전통적인 웹 애플리케이션이 'HTML form'을 사용하듯이, REST API는 CRUD라 고 알려진 표준적인 메서드와는 논리적으로 매핑되지 않는 애플리케이션 고유의 행동을 컨트롤러 리소스의 도움을 받아 수행한다. 일반적으로 컨트롤러 이름은 URI 경로의 제일 마지막 부분에 표시되며, 계층적으 로 뒤따르는 자식 리소스는 없다. 다음 예제는 클라이언트가 사용자에게 경고를 재 전송하게 하는 컨트롤러 리소스다.

POST /alerts/245743/resend

PUT 과 POST의 차이

PUT

post와 가장 큰차이는 put 메서드는 자원의 식별자를 이미 알고있는 상태여야한다는 점이다. put 메서드는 식별자의 자원을 http 메세지로 함께 넘어온 엔티티로 교체한다. response code는 200(ok), 204(no content)를 사용한다. 다만 put 메서드로 넘어온 식별자가 꼭 존재하고있는 식별자일 필요는 없다. 존재하지않는 식별자를 넘길수도있는데 이런 경우엔 넘어온 식별자를 id로 하는 새 자원을 생성하고 201(created) 응답을 한다. 식별자를 id로 사용할수없는 경우엔 에러코드로 응답한다.

POST

post 메서드는 기존에 알고있던대로 등록에 관한 내용이다. http 메세지로 넘어온 엔티티를 새로운 자원으로 등록한다.
새로운 자원으로 등록하지않을 수도있는데 이런 경우엔 200(ok)이나 204(no content) response code로 응답한다. 새로운 자원으로 만들어진 경우에는 201(created) response code로 응답하며 신규 생성된 자원의 위치를 헤더에 포함해야한다. 무슨 말이냐하면 예를들어 게시판에 새로 게시물을 등록하면 이를 따라갈수있는 위치를 응답 헤더에 넣어야한다는 의미다.

201 created
Location: /board/2

차이

새 자원을 생성한다는 점에서 POST랑 같네?! 라고 생각할수도있지만 POST와 PUT의 가장 큰 차이는 POST는 request message로 포함된 엔티티를 이용해 새로운 자원을 생성해 내는것이고, PUT은 request message와 함께 넘어온 식별자의 자원을 만드는것이다.

똑같은 요청이 POST로 2번 날아오면 POST는 2개의 자원을 생성한다. 게시판에 글쓰기 요청을 2번 날리면 2개의 게시물이 등록되는것이다. PUT으로 동일한 요청을 2번 날린다고 생각해보자. 이때 PUT은 식별자를 포함해야한다. 다만 꼭 존재하는 식별자를 포함할 필요는 없으므로 존재하지않는 식별자로 요청을 하게되면 이때는 POST와 동일하게 자원을 생성한다. 하지만 두번째 요청에선 이미 첫번째 요청에서 생성된 자원이 있으므로 자원을 생성하지않고 교체하게된다. 이 부분이 POST와 PUT이 달라지게된다.

post request 예제(요청할때 식별자를 보내지않음)

POST /board

{  
//...  
}

put request 예제(요청할때 식별자를 보내야함, 그게 실제로 존재하는것인지는 중요치 않음)

PUT /board/2

{  
//...  
}  

HTTP 메소드 별 특징

HTTP 메소드	RFC	요청에 Body가 있음	응답에 Body가 있음	안전	멱등(Idempotent)	캐시 가능
GET	RFC 7231	아니오	예	예	예	예
HEAD	RFC 7231	아니오	아니오	예	예	예
POST	RFC 7231	예	예	아니오	아니오	예
PUT	RFC 7231	예	예	아니오	예	아니오
DELETE	RFC 7231	아니오	예	아니오	예	아니오
CONNECT	RFC 7231	예	예	아니오	아니오	아니오
OPTIONS	RFC 7231	선택 사항	예	예	예	아니오
TRACE	RFC 7231	아니오	예	예	예	아니오
PATCH	RFC 5789	예	예	아니오	아니오	예