Spring - REST API 와 RESTful

API(Application Programming Interface)

API 는 프로그램이나 애플리케이션 간에 서로 소통할 수 있도록 해주는 방법입니다. 두 프로그램이 서로 정보를 주고받기 위한 규칙이나 약속이라고 생각하면 됩니다.

예를 들어, 스마트폰의 날씨 앱을 사용할 때, 그 앱이 날씨 데이터를 서버에서 가져오는 과정이 API를 통해 이루어집니다. 날씨 앱은 API 를 통해 서버에 "현재 날씨는?" 이라고 요청하고, 서버는 그에 대한 응답으로 날씨 정보를 돌려줍니다.

REST(Representational State Transfer)

REST 는 웹 기반의 API 설계를 위한 아키텍쳐 스타일입니다. REST 는 HTTP 프로토콜을 사용해서 웹 상에서 리소스(데이터)를 정의하고 조작하는 방법을 규정합니다. 이 방식은 간단하고, 클라이언트(사용자)와 서버 간의 통신을 효율적으로 만들어줍니다.

REST의 주요원칙
1. 무상태성(Stateless): 각 요청은 독립적이어야 합니다.모든 필요한 정보는 요청에 포함되어야 합니다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만 처리합니다. 이로 인해 서비스의 자유도가 높아지고 불필요한 정보를 관리하지않아 구현이 단순해 집니다.

2. 리소스 기반(Resourced-Based): API 는 리소스(데이터)에 대한 URI(고유한 주소)를 통해 접근합니다. 예를 들어 /users 는 사용자 데이터를 나타내는 리소스입니다.

3. 표현(Representation): 리소스는 다양한 형식(JSON, XML 등) 으로 표현할 수 있습니다. 클라이언트는 원하는 형식으로 데이터를 요청할 수 있습니다.

REST의 특징
1. 균일한 인터페이스
HTTP 표준에 따라 안드로이드, IOS 플랫폼 특정언어나 기술에 종속되지 않고 모든 플랫폼에 사용할 수 있으며, URI 로 지정한 리소스에 대한 조작이 가능한 아키텍쳐 스타일을 의미합니다.

2. 캐시 가능
HTTP 라는 기본 웹 표준을 그대로 사용하여 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있습니다. 따라서 HTTP 가 가진 캐싱기능을 적용할 수 있습니다. 이를 통해 서버 부하를 줄이고 성능을 향상시킬 수 있습니다.

3. 자체 표현 구조
REST API 메세지만으로 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있습니다.

REST API
REST 원칙을 따르는 API입니다. 즉, 클라이언트와 서버가 RESTful 방식을 통해 서로 소통하고 데이터를 주고받는 API입니다. REST API 는 다음과 같은 HTTP 메서드를 사용합니다.

• GET : 리소스를 조회할 때 사용
• POST : 새로운 리소스를 생성할 때 사용
• PUT : 기존 리소스를 수정할 때 사용
• PATCH: 기존 리소스를 일부 수정할 때 사용
• DELETE : 리소스를 삭제할 때 사용

예를 들어, /users 엔드포인트에 GET 요청을 보내면 모든 사용자 정보를 가져오는 것이고, POST 요청을 보내면 새로운 사용자를 추가하는 것 입니다.

RESTful

RESTful은 REST 원칙을 잘 따르는 API 를 설명하는 용어입니다. 즉, 잘 설계된 REST API 는 리소스를 효과적으로 표현하고, HTTP 메서드를 적절히 사용하며, 클라이언트와 서버 간의 상호작용이 간단하고 명확해야 합니다.

RESTful 한 API 를 만들기 위해서 REST API 설계 규칙을 알아보겠습니다.

URL 규칙
1. URI 경로에는 소문자를 사용합니다.

http://localhost:8080/api/post-comments 👍
http://localhost:8080/api/postComments ❌

 

2. 언더바 대신 하이픈을 URI 가독성을 위해 사용한다.
(가급적 하이픈의 사용도 최소화하며, 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에 사용합니다)

http://localhost:8080/api/post-comments 👍
http://localhost:8080/api/post_comments ❌

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

http://localhost:8080/api 👍
http://localhost:8080/api/❌

4. 행위는 포함하지 않는다(행위는 URL 대신 Method를 사용하여 전달(GET, POST, PUT, DELETE)

http://localhost:8080/api/1/posts/1 👍
http://localhost:8080/api/1/delete-post/1 ❌

5. 파일 확장자는 URI 에 포함시키지 않는다.

http://localhost:8080/api/photo 👍
http://localhost:8080/api/photo.jpg ❌

 

POST, PUT, PATCH 의 차이점

POST 와 PUT 은 크게 멱등성 유무의 차이에 있습니다.

멱등성 (Idempotency)
멱등성은 특정 연산을 여러 번 수행해도 결과가 동일하게 유지되는 성질을 의미합니다.

PUT은 멱등성을 가집니다. 같은 PUT 요청을 여러 번 보내더라도 결과는 항상 동일합니다. 예를 들어, /users/1에 대해 동일한 PUT 요청을 여러 번 보내면, 최종적으로 ID가 1인 사용자의 정보가 동일하게 업데이트됩니다.

POST는 멱등성을 가지지 않습니다. 같은 POST 요청을 여러 번 보내면 매번 새로운 리소스가 생성되므로 결과가 달라집니다. 즉, 사용자를 한 번 생성하면, 다시 같은 요청을 보내면 또 다른 사용자가 생성됩니다.

POST:

목적: 새로운 리소스를 생성할 때 사용됩니다.
리소스 생성: 클라이언트가 서버에 데이터를 보내고, 서버는 이를 처리하여 새로운 리소스를 생성합니다. 이때 생성된 리소스의 URI는 서버에서 결정합니다.
예시: /users 엔드포인트에 POST 요청을 보내면 새로운 사용자가 생성됩니다. 서버는 생성된 사용자에 대한 정보를 반환할 수 있습니다.

PUT:

목적: 기존 리소스를 수정할 때 사용됩니다. 만약 리소스가 존재하지 않으면 새로 생성할 수도 있습니다.
리소스 수정: 클라이언트는 수정할 리소스의 URI를 알고 있어야 하며, PUT 요청은 해당 URI에 있는 리소스를 완전히 대체합니다.
예시: /users/1 엔드포인트에 PUT 요청을 보내면 ID가 1인 사용자의 정보를 수정하게 됩니다.

PATCH

목적: 기존 리소스를 부분적으로 수정할 때 사용됩니다.
부분 수정: PATCH 요청은 리소스의 일부만 수정하는 데 사용됩니다. 클라이언트는 변경할 필드만 포함시켜 요청을 보낼 수 있습니다.
리소스 URI: PATCH 역시 클라이언트는 수정할 리소스의 URI를 알고 있어야 하며, 해당 URI에 대해 요청을 보냅니다.
예시: /users/1에 대한 PATCH 요청은 ID가 1인 사용자의 이름만 수정합니다.

 

특징	PUT	PATCH
수정 방식	전체 대체	부분 수정
요청 본문	모든 필드를 포함해야 함	변경할 필드만 포함할 수 있음
멱등성	멱등적 (여러 번 요청해도 결과 동일)	멱등적일 수도 있으나 그렇지 않을 수도 있음

 

 

HTTP 응답 상태 코드

HTTP 응답 상태 코드는 클라이언트(예: 웹 브라우저)가 서버로부터 요청에 대한 처리 결과를 알리기 위해 사용하는 3자리 숫자 코드입니다. 이 코드는 요청이 성공했는지, 실패했는지, 그리고 어떤 종류의 응답이 돌아왔는지를 나타냅니다. 상태 코드는 주로 다음과 같은 카테고리로 분류됩니다.

1. 정보 응답 (1xx)
100 Continue: 클라이언트가 요청을 계속해도 좋다는 의미.
101 Switching Protocols: 서버가 클라이언트의 요청에 따라 프로토콜을 변경하겠다는 의미.

2. 성공 응답 (2xx)
200 OK: 요청이 성공적으로 처리되었음을 나타냅니다.
201 Created: 요청이 성공적으로 처리되어 새로운 리소스가 생성되었음을 나타냅니다.
204 No Content: 요청이 성공적으로 처리되었지만 반환할 데이터가 없음을 나타냅니다.

3. 리다이렉션 (3xx)
301 Moved Permanently: 요청한 리소스가 영구적으로 다른 URI로 이동했음을 나타냅니다. 클라이언트는 새 URI로 요청을 재전송해야 합니다.
302 Found: 요청한 리소스가 일시적으로 다른 URI에 있음을 나타냅니다. 클라이언트는 다음 요청에서 원래 URI를 계속 사용해야 합니다.
304 Not Modified: 클라이언트의 캐시된 리소스가 최신임을 나타냅니다. 클라이언트는 이전에 저장한 버전을 사용하면 됩니다.

4. 클라이언트 오류 (4xx)
400 Bad Request: 서버가 요청을 이해하지 못했거나 유효하지 않은 요청임을 나타냅니다.
401 Unauthorized: 인증이 필요함을 나타냅니다. 클라이언트는 자격 증명을 제공해야 합니다.
403 Forbidden: 요청이 서버에 의해 거부되었음을 나타냅니다. 권한이 없어서 접근할 수 없습니다.
404 Not Found: 요청한 리소스가 서버에 존재하지 않음을 나타냅니다.

5. 서버 오류 (5xx)
500 Internal Server Error: 서버에서 요청을 처리하는 중 오류가 발생했음을 나타냅니다. 서버 내부에서 문제가 발생했습니다.
502 Bad Gateway: 서버가 요청을 처리하기 위해 상위 서버와 통신하는 중 오류가 발생했음을 나타냅니다.
503 Service Unavailable: 서버가 일시적으로 사용 불가능하다는 의미입니다. 서버가 과부하 상태이거나 유지 관리 중일 수 있습니다.

---

Reference: https://tao-tech.tistory.com/11

REST API, RESTful API란?