RESTful API 의미와 설계 규칙

1. REST API/ RESTful API 의미

REST란 REpresentational State Trasfer의 약어로 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처입니다.

기본 구조는 다음과 같습니다.

• 자원(Resource): URI
• 행위(Verb): HTTP Method
• 표현(Representations)

API 개발자는 여러 아키텍처를 사용하여 API를 설계할 수 있습니다. REST 아키텍처 스타일을 따르는 API를 REST API라고 하고, REST 아키텍처를 구현하는 웹 서비스를 RESTful 웹 서비스라고 합니다. RESTful API라는 용어는 일반적으로 RESTful 웹 API를 나타내지만 REST API와 RESTful API라는 용어는 같은 의미로 사용할 수 있습니다. 

---

2. HTTP METHOD (CRUD)

HTTP METHOD에서는 GET, POST, PUT, DELETE가 대표적이다. 

• GET: 조회
• POST: 등록
• PUT:  수정
• DELETE: 삭제

멱등성: 멱등성이란 여러 번 수행해도 그 결과가 같은 것을 뜻합니다. 

• GET, PUT, DELETE는 모두 멱등하다고 할 수 있습니다.

POST방식이 GET방식보다 보안측면에서 더 좋다?

• GET과 비교하여 URL에 데이터의 정보가 들어 있지 않으므로 조금 더 안전하다고 볼 수 있다.

GET방식이 POST방식보다 속도가 빠르다?

• GET 방식은 캐싱을 하기 때문에 여러번 요청시 저장된 데이터를 활용하므로 조금 더 빠를 수 있다.

POST vs PUT

• POST와 PUT은 구분해서 사용해야한다. POST는 새로운 데이터를 계속 생성하기 때문에 요청시마다 데이터를 생성하지만, PUT은 사용자가 데이터를 지정하고 수정하는 것이기 때문에 같은 요청을 계속하더라도 데이터가 계속 생성되지는 않는다.

PUT vs PATCH

• PATCH는 이 포스트에서 다루지 않았지만, 정보를 수정할 수 있는 HTTP Method가 또 있습니다. 하지만 PUT이랑은 조금 다릅니다. PUT은 지정한 데이터를 전부 수정하는 Method이지만 PATCH는 정보의 일부분이 변경되는 방법입니다. 그래서 PUT은 멱등하지만, PATCH는 멱등할 수도 멱등하지 않을 수도 있습니다.

 

---

3. REST 아키텍쳐 스타일의 규칙

 

클라이언트-서버 구조 

• 클라이언트와 서버는 서로 독립적이어야 하며, 클라이언트는 오직 URIs 리소스만 알아야 합니다. 클라이언트와 서버의 인터페이스가 변경되지 않는 한, 이 둘은 독립적으로 개발되거나 대체될 수 있게 유지해야 합니다. (관심사의 명확한 분리)

균일한 인터페이스

• 요청은 리소스를 식별해야 합니다. 이를 위해 균일한 리소스 식별자를 사용합니다.
• 클라이언트는 원하는 경우 리소스를 수정하거나 삭제하기에 충분한 정보를 리소스 표현에서 가지고 있습니다. 서버는 리소스를 자세히 설명하는 메타데이터를 전송하여 이 조건을 충족합니다.
• 클라이언트는 표현을 추가로 처리하는 방법에 대한 정보를 수신합니다. 이를 위해 서버는 클라이언트가 리소스를 적절하게 사용할 수 있는 방법에 대한 메타데이터가 포함된 명확한 메시지를 전송합니다.
• 클라이언트는 작업을 완료하는 데 필요한 다른 모든 관련 리소스에 대한 정보를 수신합니다. 이를 위해 서버는 클라이언트가 더 많은 리소스를 동적으로 검색할 수 있도록 표현에 하이퍼링크를 넣어 전송합니다.

무상태

• 클라이언트의 모든 요청에는 해당 요청을 이해할 수 있는 모든 정보가 포함되어야합니다. 서버는 HTTP 요청에 대한 어떤 것도 저장하지 않습니다. 컨텍스트를 유지해야하는 세션, 인증과 인가에 대한 정보 또한 클라이언트에만 보관되며, 각 요청 시 해당 정보를 모두 포함하여 서버에 요청합니다.

계층화 시스템

• REST는 다중 계층 구조를 가질 수 있도록 허용합니다. (예를 들어 API 서버와 DB서버 그리고 인증 서버를 따로 둘 수 있도록). 그리고 각 레이어는 자기와 통신하는 컴포넌트 외 레이어에 대해서는 정보를 얻을 수 없습니다. 클라이언트는 REST 서버와만 상호작용할 뿐, REST가 상호작용하는 레이어나 그 외 중간 레이어들, end server에 직접적으로 요청할 수 없으며 이들의 상호작용 또한 볼 수 없습니다.

캐시 가능성

• 서버는 Response cache-control 헤더에 해당 요청이 캐싱이 가능한 지에 대한 여부를 제공해야 합니다. 이를 제공한다면 클라이언트는 Response를 캐싱하여 서버와 클라이언트 간의 상호작용을 줄이고, 성능과 서버 가용성을 늘릴 수 있습니다.

온디맨드 코드

• REST 아키텍처 스타일에서 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 일시적으로 확장하거나 사용자 지정할 수 있습니다. 예를 들어, 웹 사이트에서 등록 양식을 작성하면 브라우저는 잘못된 전화번호와 같은 실수를 즉시 강조 표시합니다. 서버에서 전송한 코드로 인해 이 작업을 수행할 수 있습니다.

---

4. REST API 설계 규칙

1. 행위를 포함하지 않는다.

X GET http://minsu20.tistory.com/users/get/1

O DELETE http://minsu20.tistory.com/users/1

자원에 대한 행위는 HTTP Method로 표현(GET, POST, DELETE, PUT)

 

2. 마지막에 슬래시(/)를 포함하지 않는다.

X   http://minsu20.tistory.com/boards/

O  http://minsu20.tistory.com/boards

 

3. 계층 관계 표현을 위해 `/`를 사용한다.

http://minsu20.tistory.com

http://minsu20.tistory.com/users

http://minsu20.tistory.com/users/{id}

http://minsu20.tistory.com/users/{id}/comments

 

4. 소문자를 사용한다.

X   http://minsu20.tistory.com/users/Post-comments

O  http://minsu20.tistory.com/users/post-comments

 

5. 언더바( _ ) 대신 하이픈( - )을 사용한다.

X   http://minsu20.tistory.com/users/post_comments

O  http://minsu20.tistory.com/users/post-comments

 

6. 파일 확장자를 사용하지 않는다.

X   http://minsu20.tistory.com/users/photo.jpg

O  http://minsu20.tistory.com/users/photo

 

7. 가능한 명사를 사용한다.

X   http://minsu20.tistory.com/get-users

O  http://minsu20.tistory.com/users

 

 

---

참고 자료

 

Http Method 란? (GET, POST, PUT, DELETE)

 

RESTful API를 위한 6가지 원칙과 네이밍

 

RESTful API 의미와 설계 규칙

 

RESTful API란 무엇인가? - RESTful API 초보자 가이드 - AWS