[Java] RESTful API 설계 방법 -1 : 이해하기

해당 글에서는 Restful API에 대해서 이해하며 이를 통해 설계를 하는 방법에 대해서 이해하기 위해 작성한 글입니다.

1) REST / RESTful API

---

 💡 REST(Representational State Transfer)란?

- 웹 애플리케이션을 개발하기 위한 아키텍처 스타일 중 하나로 클라이언트와 서버 간의 ‘통신 방식’을 규정한 것입니다.
- 해당 통신 방식은 ‘HTTP 프로토콜’을 기반으로 하며 자원, 행위, 표현 세 가지 요소로 구성됩니다.


💡 REST API (Representational State Transfer) 란?

- REST 아키텍처 스타일에 따라 구성한 API를 의미합니다.


💡 RESTful API (Representational State Transfer)란?

- HTTP를 위한 아키텍처 스타일 중 하나로 REST의 원칙을 따르는 웹 서비스를 ‘구현하는 방식’이며 웹 서비스를 개발하는 방식입니다.
- 클라이언트와 서버 간 자원을 주고받을 때 '일괄적인 방식'을 제공하며 이를 통해 서버와 클라이언트의 역할을 '명확하게 분리'하고 서로 '독립적'으로 개발할 수 있게 됩니다.

 
 

[ 더 알아보기 ]

💡 프로토콜(Protocol) 이란?

- 클라이언트와 서버 간의 통신을 위한 약속된 규칙을 말합니다.


💡 REST API와 RESTful API의 차이점은?

- REST API는 REST 아키텍처 스타일을 따르는 API이며 RESTful API는 REST API를 제공하는 웹 서비스를 의미합니다.
- 결론적으로는 RESTful API는 REST API의 원칙을 따르기 때문에 REST API보다는 조금 더 RESTful 하다고 볼 수 있습니다.


💡 Restful 하다 의미는?

- REST API의 원칙을 따라 구성한 웹 서비스를 의미합니다. 자원을 URL로 표현하고 HTTP Method를 이용해 해당 자원에 대해 CRUD 작업을 수행하며 리소스와 행위를 명시적으로 분리하여 사용함으로써 URL만 보고도 어떤 동작을 수행하는지 알 수 있도록 구성한 것을 의미합니다.


💡 API(Application Programming Interface)란?

-  응용 프로그램에서 사용할 수 있는 인터페이스를 의미합니다. 즉, 프로그램이 다른 프로그램과 상호작용하기 위한 규약입니다.
- API를 사용하면 다른 개발자가 만든 기능을 우리가 만든 프로그램에서 사용할 수 있습니다. 이를 통해 기존의 코드를 다시 작성하지 않고도 다른 기능을 활용할 수 있다는 장점이 있습니다.

 
 

2) RESTful API의 제약조건

---

💡 RESTful API를 구성하고자 할 때의 제약조건을 확인하여 구성을 해야 합니다.

 
 

1. 클라이언트-서버 아키텍처

---

💡 RESTful API는 클라이언트와 서버 간의 '엄격한 분리'와 '독립성'을 유지해야 합니다. 이를 통해 각각의 역할이 분명하게 구분되어 서로에게 영향을 미치지 않는 장점을 가집니다.

 
 

2. 상태 없음 (Stateless)

---

💡 RESTful API는 '상태'를 관리하지 않습니다. 클라이언트의 요청에 따라 서버가 응답을 반환하며 이때 클라이언트의 상태나 세션 정보를 서버에서 관리하지 않습니다. 이를 통해 서버의 확장성이 높아지고 클라이언트와 서버 간의 의존성이 낮아지는 장점을 가집니다.

 
 

3. 캐시 가능 (Cacheable)

---

💡 RESTful API는 '캐시를 사용'할 수 있어야 합니다. 서버의 응답이 캐시 가능하다면 클라이언트는 서버에 요청하여 응답을 받는 대신 캐시에서 바로 응답을 받을 수 있습니다.

 
 

4. 계층 구조 (Layered System)

---

💡 RESTful API는 '계층구조'로 구성되어야 합니다. 이를 통해 서버와 클라이언트 간의 미들웨어를 추가하여 보안, 로드밸런싱, 공유캐시 등의 기능을 추가할 수 있습니다.

 
 
 

5. 인터페이스 일관성 (Uniform Interface)

---

💡 RESTful API는 '인터페이스 일관성'을 유지해야 합니다. 이를 통해 서버와 클라이언트 간의 상호작용이 단순화되고 서버와 클라이언트 간의 의존성이 낮아지는 장점을 가집니다.

 
 

6. 자체 표현성 (Self-descriptiveness)

---

💡 RESTful API는 '자체 표현성'을 가지고 있어야 합니다. 이를 통해 클라이언트는 서버로부터 받은 응답을 해석하여 처리할 수 있으며 서버는 클라이언트의 요청을 이해하고 처리할 수 있습니다.

 
 
 

3) RESTful API 설계 과정

---

💡 RESTful API를 설계하는 과정

1. 자원(Resource)을 정의합니다.

2. 행위(HTTP Method)를 정의합니다.

3. 표현(Representation)을 정의를 합니다.

4. 상태 코드(Status Code)를 정의를 정의합니다.

5. API 문서화를 정의합니다.

 

💡 해당 과정은 아래에서 하나씩 확인해 봅니다.

 
 
 

4) REST의 요소

---

💡 REST는 자원을 표현하고 이를 조작하는 행위를 나타내는 스타일을 의미하며 RESTful은 REST의 스타일을 따르는 시스템을 의미합니다. 이에 따라 REST의 요소는 자원, 행위, 표현의 세 가지 요소를 가집니다.

 
 

1. 자원(Resource)

---

💡 자원(Resource) 이란?

- 웹 상에 존재하는 데이터나 정보와 같은 모든 것을 의미합니다. 예를 들어, 사용자, 글, 댓글, 이미지 등이 모두 자원이 될 수 있습니다.
- 자원의 이름 구성은 동사가 아닌 '명사'를 사용하는 것을 권장합니다. 동사를 사용하면 URI가 길어지고 동사의 형태가 바뀌면 URI도 바뀌어 버리기 때문입니다.

 
 

2. 행위(Verb)

---

💡 행위(Verb) 란?

- HTTP Method를 이용한 자원에 대한 행위(조회, 생성, 수정, 삭제)를 의미합니다.

HTTP Method	행위	설명	예스
GET	자원을 조회	URI로 지정된 정보를 검색합니다.	사용자 정보 조회: GET /users/{user_id}
POST	자원을 생성	URI로 지정된 위치에 새로운 자원을 생성합니다.	사용자 정보 생성: POST /users
PUT	자원을 수정	URI로 지정된 위치의 자원을 갱신합니다.	사용자 정보 수정: PUT /users/{user_id}
DELETE	자원을 삭제	URI로 지정된 위치의 자원을 삭제합니다.	사용자 정보 삭제: DELETE /users/{user_id}
PATCH	자원 일부를 수정	URL로 지정된 위치의 리소스의 일부를 수정하는데 사용이 됩니다.	사용자 이메일 수정 : PATCH /users/{user_id}

 
 

[ 더 알아보기 ]

💡 PUT과 PATCH의 차이점은?

- PUT 메서드는 ‘전체 리소스’를 교체하는 데 사용되는 반면에 PATCH 메소드는 ‘일부 리소스’를 수정하는 데 사용됩니다.
- 전체 리소스를 변경하는 경우는 모든 정보를 완전히 교체하는가 아니면 일부만 교체하는가의 차이점이 있습니다.
- 이를 실행하기 위해서는 리소스의 수정 내용을 포함하는 요청 본문을 전송해야 합니다. 일반적으로 JSON 또는 XML 형식으로 전송됩니다.

 
 
 

3. 표현(Representation)

---

💡 표현(Representation) 이란?

- RESTful에서 클라이언트와 서버 간의 데이터 통신을 위해 주고받는 '데이터 형식(JSON, XML, HTML)'을 의미합니다.

분류	JSON(JavaScript Object Notation)	XML(Extensible Markup Language)	HTML(HyperText Mark-up Language)
문법	가볍고 간결하며 쉽게 읽고 쓸 수 있음	JSON과 비교해 더 많은 데이터를 필요로하며 상세함	데이터 교환을 위한 것이 아니라 웹 페이지 렌더링을 위해 설계됨
가독성	읽고 구문 분석하기 쉽고 복잡한 데이터 구조와 배열을 지원함	읽고 구문 분석하기 쉽고 복잡한 데이터 구조와 스키마 유효성 검사를 지원함	읽고 구문 분석하기 쉽고 기본 데이터 구조와 링크를 지원함
유연성	쉽게 확장하고 사용자 정의할 수 있으며 대부분의 프로그래밍 언어를 지원함	이름 공간과 사용자 정의 태그를 지원하지만 확장하는 데 더 많은 노력이 필요함	제한된 유연성으로 복잡한 데이터 교환에는 적합하지 않음
인기도	웹 개발, 모바일 앱 및 API에서 널리 사용됨	기업 응용 프로그램 및 레거시 시스템에서 널리 사용됨	웹 개발에서 널리 사용됨, 그러나 API에는 권장하지 않음

 
 
 

5) RESTful API 상태 코드(Status Code)

---

💡 RESTful API 상태 코드 (Status Code)

- Restful API에서는 HTTP 상태코드를 사용하여 클라이언트에게 요청의 성공 또는 실패를 알려줍니다.
- 상태코드는 3자리 숫자로 표현되며 각각의 숫자는 특정한 의미를 가지고 있습니다.

 

1. 전체적인 상태코드 형태

---

상태코드	상태 정보	의미
1xx	Informational	요청이 수신되었으며 처리가 계속됨을 의미합니다.
2xx	Success	요청이 성공적으로 처리되었음을 의미합니다.
3xx	Redirection	요청이 완료되기 위해 추가 작업이 필요함을 의미합니다.
4xx	Client Error	클라이언트 오류로 인해 요청이 실패함을 의미합니다.
5xx	Server Error	서버 오류로 인해 요청이 실패함을 의미합니다.

 
 

2. 일반적으로 사용되는 상태코드 종류

---

상태코드	상태 정보	의미
200	OK	요청이 성공적으로 처리되었음을 의미합니다. 클라이언트에게 요청한 데이터를 반환합니다.
201	Created	새로운 리소스가 성공적으로 생성되었음을 의미합니다.
204	No Content	요청이 성공적으로 처리되었지만, 반환할 데이터가 없음을 의미합니다.
400	Bad Request	클라이언트 요청이 잘못되었음을 의미합니다. 요청이 잘못된 경우에는 이 상태코드를 반환합니다.
401	Unauthorized	클라이언트가 인증되지 않았음을 의미합니다.
403	Forbidden	클라이언트가 요청한 리소스에 접근할 권한이 없음을 의미합니다.
404	Not Found	요청한 리소스를 찾을 수 없음을 의미합니다.
500	Internal Server Error	서버에서 오류가 발생하여 요청을 처리할 수 없음을 의미합니다.

 
 
 

6) API 문서화

---

💡 API 문서

- RESTful API를 사용하는 클라이언트 개발자나 다른 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 문서화가 필요합니다.
- API 문서는 API URL, 자원(Resource), 행위(Verb)/HTTP Method, 표현(Representation), 상태코드, 응답 형태 등을 상세하게 기술해야 합니다.
- 위와 같은 단계를 따라 RESTful API를 설계하면 클라이언트와 서버 간 일관적인 자원 교환 방식을 보장할 수 있으며 유지보수가 용이한 API를 만들 수 있습니다.

 
 

1. API Endpoint 정의하기

---

 💡 API Endpoint 란?

- 클라이언트가 서버에게 요청을 보내어 통신을 하는 URL을 의미합니다. 예를 들어 "https://example.com/users"에서 users
는 엔드포인트를 가리키며 엔드포인트는 HTTP Method(GET, POST,. PUT, DELETE 등)와 함께 사용이 됩니다.

 

[참고] API Endpoint를 정의할 때는 다음과 같은 사항을 고려 사항

고려 사항	설명
URL 구조	일관성 있는 URL 구조를 유지해야 합니다.
HTTP Method	각 Endpoint에 대해 지원하는 HTTP Method(GET, POST, PUT, DELETE 등)을 정의해야 합니다.
Request와 Response 포맷	Request와 Response의 데이터 형식(JSON, XML, CSV 등)을 정의해야 합니다.

 
 
 

2. API Endpoint 문서화하기

---

💡 API Endpoint 문서화 란?

API Endpoint의 기능과 사용 방법에 대해서 문서를 구성한 것을 의미하며 아래와 같은 내용을 포함해야 합니다.

번호	문서화 포함 내용
1	Endpoint의 URL과 HTTP Method
2	Endpoint의 기능과 목적
3	요청(Request)과 응답(Response)의 데이터 형식
4	Request와 Response의 필수/선택적 매개변수 및 예시
5	에러 메시지와 상태 코드

 
 
 

3. API 문서화 도구 사용

---

💡 ’API 문서화 도구’를 사용하여 API 문서화를 쉽게 관리할 수 있습니다.
💡 Swagger, Postman, Apiary 등의 도구를 사용하여 Endpoint 정의와 Endpoint 문서화를 쉽게 관리할 수 있습니다.

 

[참고] 이전에 작성한 API 문서화 도구 Swagger 사용방법

[Java/Library] Swagger 이해하고 적용하기 : SpringDoc openAPI UI

 
 
 

4. API 문서 업데이트

---

💡 API는 지속적으로 변경될 수 있기 때문에 API 문서도 업데이트가 필요합니다.
💡 API가 변경되면 문서화도 함께 업데이트하여 최신 버전을 유지해야 합니다.
💡 API 문서는 상세하고 명확하게 API 문서를 작성하여 개발자와 사용자가 API를 쉽게 이해하고 사용할 수 있도록 해야 합니다.

 

 

 

 

💡 [참고] 해당 글은 다음 글에서 실제 응용을 하는 방법에 대해 다룹니다. 이를 참고하시면 크게 도움이 됩니다.

[Java] RESTful API 설계 방법 -2 : 구성하기

 
 
 

 
오늘도 감사합니다. 😀