[API] 01. Restful API란?

Restful API란?

REST API란 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스이며 REST를 기반으로 만들어진 API를 의미합니다.

 

 REST API를 알기 위해 REST와 API에 대하여 먼저 알아보겠습니다.

---

API란?

API는 정의 및 프로토콜 집합을 사용하여 두 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 메커니즘이며 Application Programming Interface(애플리케이션 프로그램 인터페이스)의 줄임말입니다.

 

다른 소프트웨어 시스템과 통신하기 위해 따라야 하는 규칙을 정의하며 웹 API는 클라이언트와 웹 리소스 사이의 게이트웨이라고 생각할 수 있습니다.

 

REST란?

REST는 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처이며 Representational State Transfer(REST)의 줄임말입니다.

 

 

REST 아키텍처 스타일 원칙

• Uniform Interface (균일한 인터페이스) : 클라이언트와 서버가 동일한 인터페이스를 통해 소통할 수 있도록 하며, 주로 HTTP 프로토콜을 사용합니다.
• Stateless (무상태성) : 각 요청이 독립적으로 처리되며, 서버는 클라이언트의 상태를 저장하지 않습니다.
• Layered System (계층화 시스템) : 요청과 응답은 여러 계층을 거쳐 전달되며, 이를 통해 보안과 확장성을 강화합니다.
• Cacheable (캐시 가능성) : 클라이언트는 응답을 캐싱할 수 있습니다. 이를 통해 성능을 개선할 수 있습니다.
• Code on Demand (온디맨드 코드) : 서버는 필요에 따라 클라이언트에 코드를 전송해 동적으로 기능을 확장할 수 있습니다 (선택적 원칙).
• Client-Server Architecture (클라이언트-서버 구조): 클라이언트와 서버의 책임을 분리하여 각각 독립적으로 발전할 수 있도록 합니다.

 

즉, Rest란

1. HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고
2. HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해
3. 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.

 

CRUD Operation이란
CRUD는 대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인
Create(생성), Read(읽기), Update(갱신), Delete(삭제)를 묶어서 일컫는 말

Create : 데이터 생성(POST)
Read : 데이터 조회(GET)
Update : 데이터 수정(PUT, PATCH)
Delete : 데이터 삭제(DELETE)

 

 

REST 구성 요소

1. 자원(Resource) : HTTP URI
2. 자원에 대한 행위(Verb) : HTTP Method
3. 자원에 대한 행위의 내용 (Representations) : HTTP Message Pay Load

 

REST의 장단점

• 장점 
  • HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
  • HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
  • Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
  • REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
  • 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
  • 서버와 클라이언트의 역할을 명확하게 분리한다.

• 단점 
  • 표준이 자체가 존재하지 않아 정의가 필요하다.
  • HTTP Method 형태가 제한적이다.
  • 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
  • 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)

 

---

 

그럼 다시 돌아와서, RESFUL  API란?

 

 

RESPT API란 REST의 원리를 따르는 API를 의미합니다.

하지만 REST API를 올바르게 설계하기 위해서는 지켜야 하는 몇가지 규칙이 있으며 HTTP 메서드와 함께 해당 규칙을 알아 보겠습니다.

 

HTTP 메서드

RESTful API에서 사용하는 주요 HTTP 메서드와 역할을 설명합니다.

• GET: 자원의 조회에 사용됩니다. 리소스를 가져올 때 주로 사용하며, 데이터 변경을 일으키지 않습니다.
• POST: 자원의 생성에 사용됩니다. 클라이언트에서 서버로 데이터를 전송해 새 리소스를 만듭니다.
• PUT: 자원의 전체 수정을 위해 사용됩니다. 기존 리소스를 업데이트합니다.
• PATCH: 자원의 부분 수정을 위해 사용됩니다. 일부분만 변경할 때 사용됩니다.
• DELETE: 자원의 삭제에 사용됩니다. 클라이언트가 특정 자원을 삭제할 때 사용합니다.

 

RESTful API 설계 예시

1. 명사형 URI 사용
   • RESTful API는 동사 대신 명사를 사용하여 리소스를 표현합니다.
   • 예시:
     • 올바른 사용: /users, /products, /orders
     • 잘못된 사용: /getUsers, /createProduct, /deleteOrder
   • 리소스의 상태나 액션은 HTTP 메서드로 전달하고, URI에는 리소스만 표시합니다.
2. 소문자 URI와 일관성 유지
   • URI에서는 대문자보다는 소문자를 사용하며, 일관성 있는 표기를 유지합니다.
   • 예시:
     • 올바른 사용: /users, /products, /orders
     • 잘못된 사용: /Users, /PRODUCTS
3. 마지막에 슬래시 (/) 포함하지 않기
   • URI 끝에 슬래시를 추가하지 않는 것이 REST 설계 규칙입니다. 대부분의 RESTful API에서는 URI 마지막에 슬래시가 없는 것을 표준으로 권장합니다.
   • 예시:
     • 올바른 사용: /products/123
     • 잘못된 사용: /products/123/
4. 언더바(_) 대신 하이픈(-) 사용
   • URI에서 여러 단어를 조합할 때는 **하이픈(-)**을 사용하여 단어를 구분합니다. 언더바는 가독성이 떨어지기 때문에 REST 설계에서는 하이픈을 권장합니다.
   • 예시:
     • 올바른 사용: /user-accounts, /order-details
     • 잘못된 사용: /user_accounts, /order_details
5. 파일 확장자를 포함하지 않기
   • RESTful API에서는 자원 형식을 나타내기 위해 파일 확장자를 사용하지 않습니다. 대신 클라이언트가 요청 시 Accept 헤더를 사용하여 원하는 응답 형식을 지정합니다.
   • 예시:
     • 올바른 사용: /products
     • 잘못된 사용: /products.json, /products.xml
6. 행위를 URI에 포함하지 않기
   • URI는 자원만 나타내며, 동작은 HTTP 메서드로 전달합니다. 예를 들어, 조회, 생성, 수정, 삭제 등의 행위는 각각 GET, POST, PUT, DELETE와 같은 메서드로 표현됩니다.
   • 예시:
     • 올바른 사용:
       • GET /users (사용자 목록 조회)
       • POST /users (사용자 생성)
       • PUT /users/{id} (특정 사용자 정보 수정)
       • DELETE /users/{id} (특정 사용자 삭제)
     • 잘못된 사용:
       • /getAllUsers, /deleteUser/{id}, /updateUser/{id}
7. HTTP 상태 코드 사용
   • RESTful API는 클라이언트에게 응답 시, 요청의 결과를 HTTP 상태 코드로 전달합니다. 각 상태 코드는 요청 성공, 실패, 잘못된 입력 등의 상황을 나타내며 클라이언트가 적절한 후속 조치를 취할 수 있게 도와줍니다.
     • 200 OK: 요청이 성공적으로 처리되었습니다.
     • 201 Created: 리소스가 성공적으로 생성되었습니다 (주로 POST 요청 후 사용).
     • 204 No Content: 요청이 성공적으로 처리되었으나 반환할 내용이 없습니다 (DELETE 요청 후 주로 사용).
     • 400 Bad Request: 잘못된 요청이 전달되었습니다.
     • 404 Not Found: 요청한 리소스를 찾을 수 없습니다.
     • 500 Internal Server Error: 서버에서 요청을 처리하는 중에 오류가 발생했습니다.
   • 예시:
     • GET /users/123 요청이 성공하면 200 OK와 사용자 데이터를 반환
     • POST /users 요청으로 사용자 생성 시 201 Created와 새 사용자 정보를 반환
     • DELETE /users/123 요청이 성공하면 204 No Content 응답

 

RESTFUL이란 REST의 원리를 따르는 시스템을 의미합니다. 하지만 REST를 사용했다 하여 모두가 RESTful 한 것은 아닙니다.  REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있습니다.