[RESTful API]RESTful API란

출처 

ChatGPT

---

RESTful API란?

REST의 정의

REST(Represesntational Stat Tranfer)는 로이 필링(Roy Fielding)이 2000년 박사 논문에서 소개한 소프트웨어 아키텍처 스타일이다. REST는 웹 기반 시스템에서 자원을 처리하는 데 있어서 HTTP를 사용하는 특정한 규칙과 제약을 기반으로 한다.

 

RESTful API의 특징

RESTful API는 REST 아키텍처 스타일을 따르는 API를 말한다. 주로 HTTP 프로토콜을 기반으로 해 자원(Resource)을 네트워크를 통해 주고받을 수 있게 설계된다.

 

주요 특징

1. 무상태성 Statelessness

• 서버와 클라이언트의 모든 요청은 서로 독립적이며, 이전 요청과 다음 요청 사이에 상태를 저장하지 않는다. 모든 요청은 필요한 모든 정보를 포함해야 한다.

2. 자원의 표현 Representation

• 클라이언트는 서버의 자원에 접근할 수 있으며, 자원은 다양한 형태(JSON, XML, HTML 등)로 표현된다. JSON이 가장 많이 사용된다.

3. 통합된 인터페이스 Uniform Interface

• REST는 자원을 명확하게 식별하고 조작할 수 있는 일관된 인터페이스를 제공한다. 이를 통해 서로 다른 클라이언트가 동일한 방식으로 자원을 요청할 수 있다.

4. 캐시 가능성 Cacheability

• HTTP 프로토콜의 장점을 활용하여, 클라이언트는 응답 데이터를 캐시할 수 있다. 이를 통해 성능 향상과 서버 부하 감소를 꾀할 수 있다.

5. 계층형 시스템 Layered System

• 클라이언트는 중간 서버(프록시, 게이트웨이 등)를 통해 최종 서버에 접근할 수 있다. 이를 통해 시스템의 확작성과 보안성을 확장시킬 수 있다.

6. 클라이언트-서버 구조 Client-Server Architecture

• 클라이언트와 서버는 서로 독립적으로 개발되고 운영된다. 클라이언트는 사용자 인터페이스를 담당하며, 서버는 데이터 저장 및 비즈니스 로직을 처리한다.

7. 코드 온 디맨드 Code on Demand, 선택적

• 서버에서 클라이언트로 코드(JavaScript 등)를 전송하여 실행할 수 있지만, 이는 선택적이다.

 

RESTful API와 HTTP 메소드

RESTful APII에서는 HTTP 메소드를 통해 자원을 다룬다. 각 메소드는 특정한 CRUD (Create, Read, Update, Delete) 연산과 연결된다.

HTTP 메소드	기능	설명	CRUD 연산
GET	조회	서버에서 자원을 가져온다.	Read
POST	생성	서버에 새 자원을 생성한다.	Create
PUT	수정	서버의 자원을 전체적으로 업데이트한다.	Update
PATCH	부분 수정	서버의 자원을 부분적으로 업데이트한다.	Update
DELETE	삭제	서버에서 자원을 삭제한다.	Delete

 

예시 : 사용자 자원 처리

 

• GET /users: 모든 사용자 목록을 가져온다.
• GET /users/{id}: 특정 사용자의 정보를 가져온다.
• POST /users: 새 사용자를 생성한다.
• PUT /users/{id}: 특정 사용자의 정보를 전체적으로 업데이트한다.
• PATCH /users/{id}: 특정 사용자의 정보를 부분적으로 업데이트한다.
• DELETE /users/{id}: 특정 사용자를 삭제한다.

RESTful API의 URI 설계

RESTful API에서는 자원의 식별과 접근을 위해 URI (URI Resource Identifier)를 사용한다.

URI 설계는 다음과 같은 원칙을 따른다.

1. 자원(Resource)을 명사로 표현

• URI는 자원을 명사 형태로 표현해야 한다.
• 예: '/users', '/products', '/orders'

 

2. 계층 구조

• URI는 자원의 계층 구조를 반영해야 한다.
• 예: '/users/{userId}/orders/{orderId}'

3. 소문자 사용

• URI는 소문자로 작성해야 한다.
• 예: '/users', '/products'

4. 동사나 CRUD 관련 용어 사용 자제

• HTTP 메소드가 CRUD 기능을 설명하므로, URI에 동사나 CRUD 관련 용어를 사용하지 않는다.
• 올바른 예: '/users'
• 잘못된 예: '/getUsers', '/createUser'

5. 쿼리 파라미터(Query Parameters) 사용

• 필터링, 정렬, 검색 등은 쿼리 파라미터를 사용하여 처리한다.
• 예: '/users?sort=age', '/products?category=electronics'

 

RESTful API의 응답 상태 코드

HTTP 상태 코드는 클라이언트가 요청한 작업의 결과를 명확히 전달하는 데 사용된다.

상태 코드	설명	상세
200 OK	성공	요청이 성공적으로 처리되었다.
201 Created	생성됨	새로운 자원이 성공적으로 생성되었다.
204 No Content	성공 (내용 없음)	요청이 성공적으로 처리되었으나 응답 데이터가 없다.
400 Bad Request	잘못된 요청	요청이 잘못되었다. (유효성 검사 실패 등)
401 Unauthorized	인증 필요	인증이 필요하다
403 Forbidden	금지됨	서버가 요청을 거부했다.
403 Not Found	없음	요청한 자원을 찾을 수 없다
500 Internal Server Error	서버 오류	서버에 오류가 발생했다.

 

RESTful API의 대이터 포맷

RESTful API의 응답 데이터는 주로 JSON 형식으로 전달된다. JSON은 가독성이 좋고, 다양한 프로그래밍 언어에서 쉽게 처리할 수 있다.

 

예시 : JSON 응답

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

 

 

RESTful API 설계 모범 사례

1.버전 관리

 

• API 버전을 URI나 HTTP 헤더에 포함시켜 관리한다.
• 예: '/v1/users', '/api/v2/products'

2. 에러 처리

• 명확한 에러 메시지와 상태 코드를 사용하여 클라이언트가 오류를 이해할 수 있도록 한다.
• 예

{
  "error": "InvalidRequest",
  "message": "The 'name' field is required."
}

 

 

 

 

3. 보안

 

• HTTPS를 사용하여 데이터 전송을 암호화한다.
• 인증 및 권한 부여 메커니즘 (예: OAuth, JWT)을 사용한다.

4. 문서화

 

• API 문서를 제공하여 사용자가 쉽게 이해하고 사용할 수 있도록 한다.
• 예: Swagger, OpenAPI를 사용한 문서화

5. 자원의 페이징 Paging

 

• 많은 양의 데이터를 처리할 때는 페이징을 구현하여 성능을 향상시킨다.
• 예: '/users?page=1&limit=10'

6. 속도 제한 Rate Limiting

 

• 클라이언트의 요청 수를 제한하여 서버 자원을 보호한다.
• 예: 시간당 1000 요청 제한

7. HATEOAS Hypermedia as the Engine of Application State

• 응답 데이터에 관련 링크를 포함시켜 클라이언트가 다른 관련 자원에 쉽게 접근할 수 있도록 한다.
• 예

{
  "id": 123,
  "name": "John Doe",
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders"
  }
}