이번 포스팅은 API와 REST란 무엇인지 간단하게 설명을 한 후에 RestfulAPI에 대해 작성해보려합니다.

1. API

API는 쉽게, 웨이터의 역할을 한다고 생각하시면 쉽습니다. 웨이터는 손님에게 메뉴를 알려주고, 주방에 주문받은 요리를 요청합니다. 그다음 주방에서 완성된 요리를 손님께 다시 전달하죠. API도 똑같은 역할을 합니다.

API는 프로그램(=손님)이 주문할 수 있도록 명령 목록(=메뉴)를 정리하고, 명령(=주문)을 받으면 응용프로그램(=요리사)와 상호작용하여 요쳥된 값(=메뉴)를 전달합니다.

다시 정리하자면, 소프트웨어 간 상호작용을 가능하게 하는 규약으로, 요청을 받아 처리하고 결과를 반환하는 역할을 하는 것입니다.

API의 역할

1) API는 서버와 데이터베이스에 대한 출입구 역할

API는 중요한 정보가 저장되어있는 데이터베이스의 접근에 제한을 하는 출입구 역할을 하며, 권한을 가진 사람만 접근성을 부여해주는 역할을 합니다.

2) 애플리케이션과 기기가 원활하게 통신하도록 도움

애플리케이션은 어플이나 프로그램을 말하는데요, API는 애플리케이션과 기기가 서로 정보를 교환하고 상호 작용을 할 수 있도록 돕는 역할을 합니다.

예를 들어 사용자가 스마트폰의 날씨앱을 이용해서 현재 위치한 곳의 날씨를 알고싶어한다고 가정해봅시다. 스마트폰에서 API를 통해 위치 정보를 애플리케이션에 쏘면, 날씨 측정 및 예측 애플리케이션이 현재의 날씨를 데이터를 API를 통해 스마트폰으로 제공한다고 생각하시면 됩니다.

3) 모든 접속을 표준화

API는 모든 접속을 표준화하기 깨문에 기계, 운영체제와 상관없이 누구나 동일한 엑세스를 얻을 수 있어야합니다. 크롬에서는 실행되는데 사파리에서 실행되지 않으면 안되겠죠?

API의 유형

1) private API

내부 API로, 회사 개발자가 자체 제품과 서비스를 개선하기 위해 내부적으로 발행합니다. 따라서 제 3자에게 노출되지 않습니다.

2) public API

개방형 API로, 모두에게 공개됩니다. 누구나 제한 없이 API를 사용할 수 있는 게 특징입니다.

3) partner API

기업이 데이터 공유에 동의하는 특정인들만 사용할 수 있습니다. 비즈니스 관계에서 사용되는 편이며, 종종 파트너 회사 간에 소프트웨어를 통합하기 위해 사용됩니다.

2. REST

REST란 (Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미합니다.

정확히는,

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

한 줄로 쉽게 정의하자면 “HTTP 메서드를 통해 자원을 처리하도록 설계된 아키텍쳐”라고 할 수 있겠습니다 :)

구성요소

1) 자원(Resource): URI

웹 상에서 모든 정보는 리소스로 표현됩니다. 웹 상에 보이는 문서, 이미지, 서비스 처리 결과 등이 리소스가 될 수 있습니다.

리소스는 쉽게 도서관에 꽂혀있는 책이라고 생각하시면 됩니다. 책마다 고유한 바코드가 있듯이, 웹 상의 리소스는 고유한 URI를 통해 식별됩니다. 예를 들어, 웹 상의 자원이 "사용자 정보"일 경우, 그 자원은 "/users/123"과 같은 URI로 표현될 수 있습니다.

2) 행위(Verb): HTTP Method

서버에 대한 클라이언트의 요청 유형을 나타냅니다. RESTful API는 주로 다섯 가지 HTTP 메서드(GET, POST, PUT, DELETE, PATCH)를 사용하여 리소스에 대한 CRUD(Create, Read, Update, Delete) 연산을 수행합니다.

아래는 각 메서드에 대한 설명과 예시입니다.

Method	용도	예시
GET	리소스 조회	도서관에서 책의 정보 조회 (작가/제목 검색 등)
POST	리소스 생성	새로운 책 추가 (새 책 기증 등)
PUT	리소스 전체적으로 수정	책의 정보 업데이트 (찢어진 책 교체, 새로운 시리즈 추가 등)
DELETE	리소스 삭제	책을 도서관에서 제거
PATCH	리소스 일부 수정	책의 정보가 잘못 기입된 경우 해당 정보만 수정

3) 표현(Representation of Resource)

클라이언트와 서버 간의 교환되는 리소스의 상태를 ‘표현’이라고 합니다. 표현은 리소스의 정보를 담고 있는 데이터 형식을 말합니다. JSON은 가독성이 높고 용량이 적어 가장 일반적으로 사용되는 데이터 포맷입니다.

쉽게 설명해서 도서관에 등록된 책의 제목, 저자, 출판년도에 대한 데이터를 보기 좋게 저장을 해둔 것입니다.

{
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925,
  "ISBN": "123456789"
}

REST의 특징

1) 클라이언트-서버 구조(Client-Server Architecture)

자원이 있는 쪽이 서버, 자원을 요청하는 쪽이 클라이언트가 됩니다. 서버는 주료 API를 제공하고, 비즈니스 로직 처리 및 저장을 책입집니다. 클라이언트와 서버가 각각 독립적으로 분리되어 있어, 서로의 개발과 확장성에 유연합니다

ex) 웹 애플리케이션에서 사용자의 브라우저(클라이언트)가 서버에 페이지를 요청하고, 서버는 해당 요청에 대해 HTML 페이지를 반환하는 경우

2) 무상태성(Stateless)

HTTP 프로토콜은 기본적으로 무상태인데, REST도 똑같이 무상태입니다. 따라서 클라이언트의 요청을 완전히 별개의 것으로 인식하며 이전의 요청이 다음의 요청에 연관되지 않습니다. 이를 통해 서버의 처리 방식에 일관성을 부여하고 부담이 줄어들게 됩니다.

💡 무상태? 클라이언트의 상태(state)를 서버에 저장하지 않는다는 뜻

ex) 쿠키, 토큰과 같은 인증 정보 요청을 하지 않은 경우, 홈페이지에 로그인 후 다른 페이지로 이동했다가 다시 돌아왔을 때 서버는 이전에 로그인을 성공했단 사실을 기억하지 못하고 다시 로그인 페이지를 보여줍니다.

3) 캐시 처리 가능(Cacheable)

REST는 응답 캐시를 적용할 수 있어 대량의 요청을 효율적으로 처리할 수 있습니다. 이를 통해 응답 시간이 빨라지고 성능, 서버와 같은 자원 이용률을 향상시킬 수 있습니다.

ex) 웹 서버가 사용자의 프로필 이미지 요청에 대해 이미지 데이터와 함께 "Cache-Control" 헤더를 설정하여 응답합니다. 이 헤더는 클라이언트 브라우저에 해당 이미지를 일정 기간 동안 캐시하도록 지시합니다. 따라서, 같은 이미지를 다시 요청할 때 서버에 요청하지 않고 로컬 캐시에서 빠르게 가져올 수 있습니다.

4) 계층화 시스템(Layered System)

클라이언트는 최종 서버가 아닌, 중간 서버와도 통신할 수 있습니다.

ex) 사용자가 웹 사이트에 접속하려 할 때, 요청은 로드 밸런서(중간 서버)를 거쳐 실제 웹 서버로 전달됩니다. 이 로드 밸런서는 사용자로부터의 요청을 여러 서버에 분산시켜 부하를 관리합니다. 사용자는 로드 밸런서의 존재를 알 필요가 없으며, 마치 직접 웹 서버와 통신하는 것처럼 느낍니다.

5) 코드 온 디맨드(Code on Demand, 선택적)

서버로부터 클라이언트가 실행할 코드를 전송할 수 있으나, 이는 선택적 기능입니다.

ex) 웹 어플리케이션이 사용자에게 새로운 기능을 제공하기 위해, 서버로부터 자바스크립트 코드 조각을 전송받아 클라이언트 측에서 실행합니다. 이 코드는 클라이언트의 웹 페이지에 동적인 기능을 추가하거나 업데이트 합니다.

6) 일관된 인터페이스(Uniform Interface)

URI로 지정한 자원에 대한 조작을 통일되고 한정적인 인터스페이스로 수행하며, HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능합니다.

ex) REST API를 통해 데이터베이스에 저장된 사용자 정보에 접근하는 경우, 클라이언트는 HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하여 사용자 정보를 조회, 추가, 수정, 삭제하는 요청을 할 수 있습니다.

REST의 장단점

장점

1) 언어와 플랫폼에 독립적입니다.

2) REST API 메세지가 의도하는 바를 명확하게 나타내 의도를 쉽게 파악할 수 있습니다.

3) REST가 지원하는 프레임워크나 언어 등 도구들이 없어도 구현이 가능합니다.

4) HTTP를 사용하므로 기존 웹 인프라를 사용 가능합니다.

5) 서버와 클라이언트의 역할을 명확하게 분리할 수 있습니다.

6) 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화합니다.

단점

1) HTTP 프로토콜만 사용이 가능합니다.

2) p2p 통신 모델을 가정하여 둘 이상을 대상으로 하는 분산 환경에 유용하지 않습니다.

3) 보안, 정책 등에 대한 표준이 없습니다.

3. REST API

REST API는 인터넷을 통해 두 소프트웨어 컴포넌트가 통신하는 방법을 정의하는 아키텍처 스타일입니다.이해가 어려우시죠? 인터넷을 통해 서로 다른 소프트웨어가 서로 소통할 수 있도록 돕는 규칙이나 프로토콜로, REST와 API 두 가지의 개념을 결합했다고 생각하시면 쉽습니다.

4. RESTful API

RESTful API는 REST 원칙을 엄격하게 준수하는 API를 지칭합니다.다시 말해, REST 아키텍처 스타일에 따라 설계된 API가 RESTful하다라고 말할 수 있는 것입니다.

REST API와의 차이점으로는 RESTful API가 조금 더 REST 아키텍처 원칙을 엄격하게 따르고 있다고 생각하시면 됩니다. RESTful API를 활용하면 일관되고, 예측 가능하고 안정적인 서비스를 제공할 수 있습니다.

파이썬을 기반으로한 웹 프레임워크의 대표주자인 FastAPI를 사용하여 간단한 사용자 관리 시스템의 RESTful API를 구현하는 예시를 들어보겠습니다.

FastAPI 설치

우선 FastAPI와 Uvicorn(ASGI 서버)을 설치합니다.

pip install fastapi uvicorn

본격적인 CRUD 예시

1) 기본 설정 및 정의

FastAPI 애플리케이션을 시작하기 위한 기본 코드 구조입니다.

먼저, 책에 대한 모델을 Pydantic을 사용하여 정의합니다. (Pydantic은 데이터 검증과 설정 관리를 위한 Python 라이브러리입니다.)

from pydantic import BaseModel

class Book(BaseModel):
    title: str
    author: str
    year: int
    isbn: str
    is_borrowed: bool = False

2) Create(생성)

도서관에 새로운 책을 추가하는 기능입니다. POST 메소드를 사용합니다.

from fastapi import FastAPI, HTTPException
app = FastAPI()

books = {}

@app.post("/books/")
async def add_book(book: Book):
    if book.isbn in books:
        raise HTTPException(status_code=400, detail="Book already exists.")
    books[book.isbn] = book
    return book

3) Read(조회)

등록된 책의 정보를 조회하는 기능은 GET 메소드를 사용합니다. 아래의 예시는 isbn 을 통해 정보를 조회하는 코드입니다.

@app.get("/books/{isbn}")
async def get_book(isbn: str):
    if isbn not in books:
        raise HTTPException(status_code=404, detail="Book not found.")
    return books[isbn]

4) Update(업데이트)

책의 대출 상태를 변경하는 기능입니다. 책을 빌리거나 반납하는 과정을 PATCH 메소드를 통해 처리합니다.

@app.patch("/books/{isbn}")
async def borrow_book(isbn: str, is_borrowed: bool):
    if isbn not in books:
        raise HTTPException(status_code=404, detail="Book not found.")
    books[isbn].is_borrowed = is_borrowed
    return {"message": "Book updated successfully.", "is_borrowed": is_borrowed}

5) Delete(제거)

도서관 목록에서 책을 제거하는 기능입니다. DELETE 메소드를 사용합니다.

@app.delete("/books/{isbn}")
async def remove_book(isbn: str):
    if isbn not in books:
        raise HTTPException(status_code=404, detail="Book not found.")
    del books[isbn]
    return {"message": "Book removed successfully."}

6) 실행 및 테스트

API 서버를 실행하기 위해 터미널에서 다음 명령어를 입력합니다

uvicorn main:app --reload

명령어가 성공적으로 실행이 됐을 때, http://127.0.0.1:8000/docs에서 API를 테스트할 수 있습니다. 그리고 여기서 여기서 main은 Python 스크립트 파일 이름입니다.

공부를 하면서 기억하고 싶은 내용들이 점점 늘어나 이번 글은 다소 길어진 것 같습니다.

제가 이해하기 위해 개념 하나하나 예시를 들어가며 설명을 했는데, 이 글을 읽는 분들도 API부터 RESTful API 까지의 개념이 모두 이해가 되셨으면 좋겠습니다.

만약 이 개념에 대해 더 공부를 하고자하는 분들은, 아래의 링크 강의를 추천드립니다. 저도 이번 주말에 아래의 강의를 들으며 HTTP 웹 기본 지식에 대해 다시 짚고 넘어갈 생각입니다.

(참고로 현재 중견기업에 종사하는 백엔드 개발자들의 추천을 받은 강의입니다.)

모든 개발자를 위한 HTTP 웹 기본 지식 강의 - 인프런

지금까지 긴 글 읽어주셔서 감사합니다 🙂

---

REFER

API란? 비개발자가 알기 쉽게 설명해드립니다! - wishket

[네트워크] REST API란? REST, RESTful이란?

[Web] API란? REST API란? RESTful 이란? REST 구성 요소, 특징, 장단점