[REST API]2. REST API 디자인 가이드 ✏️

REST아키텍처 설계를 위한 몇 가지 지침 ✏️

 

REST API를 만들 때 지켜야 하는 규칙 외에 "꼭 지켜야만 하는 것"은 아니지만 숙지하고 지키면 좋은 지침들이 몇 가지 있다.

기술 면접 질문 / 시험에도 자주 등장하니 함께 알아보도록 하자!

---

1. physical URL을 사용하지 않을 것. 대신 logical URL을 사용할 것.

• physical URL이란 XML파일과 같은 물리적인 것을 가리킨다. => http://www.acme.com/inventory/product003.xml
• logical URL은 물리적 파일을 의미하지 않는다. 물론 위와 같이 .xml 확장자를 사용하더라도 콘텐츠가 동적으로 생성될 수는 있으나, logical이라는 것은 "인간이 이해할 수 있는 것" 이어야 한다.
• http://www.acme.com/inventory/product/003 => REST를 이해하는 유저가 해당 logical URL을 봤을 때, inventory(물품 목록)에서 product(상품)들 중 003번 상품을 가지고 무언가를 하겠구나! 하고 이해할 수 있다.

 

2. 쿼리는 너무 많은 데이터를 반환하지 않아야 한다. 만약 그래야 한다면 페이징 메커니즘을 제공해야 한다.

• ex) "제품 목록" GET요청은 n개의 첫 번째 제품(예: 첫 번째 10개)을 next/prev링크와 함께 반환해야 한다.
• ex) /inventor/product?limit=10&offset=40

 

3. REST응답으로 무엇이든 보낼 수 있지만, 응답에 대한 내용이 잘 문서화 되어있는지 확인하고, output format (응답 데이터 포맷)을 쉽게 변경해선 안 된다. (기존 클라이언트가 손상될 수 있다.)

• 응답 데이터가 XML인 경우 스키마 또는 DTD로 문서화 해야 한다. DTD란?

[XML] DTD를 사용하여 XML 구조의 정의 - DTD란?

 

4. 클라이언트가 URL을 구성하게 두지 말고, 실제 URL을 응답에 포함하여 클라이언트가 이것을 사용할 수 있도록 해야 한다.

• 이것이 무슨 뜻이냐면
• www.example.com/board/{id} => 이렇게 api를 제공하지 말고
• www.example.com/board 의 리스폰스에 detail로 갈 수 있는 url을 응답 데이터에 보내라는 뜻
• ex) {id:1, content: 'blahblah', url: www.example.com/board/1} => 이런 식으로

 

5. GET 요청은 절대로 서버 상태를 변경해선 안 된다. 그 어떤 것이든 서버의 상태를 변경하는 것이라면 POST나 PUT, DELETE 등의 다른 메서드를 사용해야 한다.

 

4번에 대해선 동의하기가 힘들었다. 굳이? 클라이언트가 URL을 구성하는게 어려운 것도 아니고, 저런 방식을 사용해서 굳이 응답 데이터의 크기를 키울 필요가 있을까 싶었다.

4번에 대한 포인트는 내가 생각했을 때 "데이터와 데이터에 대한 정보는 전적으로 서버측에서 관리해야 한다" 는 관점에서 작성된 지침 같았다. detail페이지를 조회하기 위해 url을 클라이언트에서 생각해서 조합하여 그 url로 요청하는게 아니라, 서버측에서 detail위치는 여기야! 하고 알려주라는 것이다. 그러니 알아서 유연하게 적용하면 될 것 같다..

 

---

참조

• http://rest.elkstein.org/2008/02/rest-design-guidelines.html