좋은 REST API란?

None·2024년 7월 4일

API

목록 보기

1/1

REST API

교내 동아리 웹개발 프로젝트를 진행하면서 설계에 부족했던 부분들이 많았다는 것을 깨닫게 됐다. API 설계의 필요성을 느끼고 설계를 하던 중 REST API라는 것을 알게 됐고, 이번 글에서는 공부한 내용으로 REST API에 대해서 다뤄보고자 한다.

1. API란? 🌐

API란 무엇인가 ❔

API(Application Programming Interface)는 소프트웨어 애플리케이션 간의 상호 작용을 위한 규칙과 도구의 집합을 의미한다. API는 두 소프트웨어 컴포넌트가 서로 통신할 수 있도록 하는 규칙, 계약 등의 역할

좀 더 쉽게 이해해보자면, 클라이언트와 서버가 있을 때 클라이언트가 요청(Request)했을 시 서버가 응답(Response)해주는 과정에서, 두 소프트웨어가 어떻게 요청과 응답을 보내면 되는지 규칙을 정한 것이다.

API의 개념

API의 주요 개념은 4가지로 구분할 수 있다.

엔드포인트(Endpoints)

API는 특정 URL 경로로 접근할 수 있는 여러 엔드포인트를 제공한다. 각 엔드포인트는 특정 기능이나 데이터를 제공한다.

HTTP 메소드

REST API(RESTful API)의 경우, 주로 GET, POST, PUT, DELETE와 같은 HTTP 메소드를 사용하여 요청을 보낸다.

요청(Request)와 응답(Response)

클라이언트가 API를 호출하면 서버는 요청을 처리하고 결과를 응답으로 반환한다. 요청에는 필요한 데이터가 포함되며, 응답에는 요청 결과가 포함된다.

데이터 형식

API는 JSON, XML 등의 데이터 형식을 사용하여 클라이언트와 서버 간에 데이터를 주고받는다.

API의 특징

추상화	특정 기능을 쉽게 사용할 수 있도록 한다.
재사용성	여러 애플리케이션에서 재사용할 수 있도록 설계. 코드의 중복을 줄이고 유지보수를 용이하게 한다.
모듈화	소프트웨어를 모듈화하여, 각 모듈이 독립적으로 개발, 테스트, 유지보수 될 수 있도록 한다.
표준화	서로 다른 언어와 플랫폼 간의 통합을 가능하게 한다.
보안	인증, 권한 부여, 암호화 등의 보안 매커니즘을 통해 데이터를 보호한다.

API는 왜 사용할까? 💻

https://appmaster.io/api/_files/PqV7MuNwv89GrZvBd4LNNK/download/

지금까지 API에 대해서 알아보는 시간을 가졌다. 그럼 이제 은연 중에 그런 생각이 들 것이다. API는 왜 사용할까? 어떤 상황에 사용할까?

데이터 교환

API는 다른 소프트웨어와 데이터를 교환할 수 있는 방법을 제공한다. 프로그램에 API로 연결하면 데이터를 공유, 처리 또는 조작할 수 있다. 토스는 데이터 교환 API를 통해서 한 개인의 계좌 및 카드 내역 정보를 앱 내에서 확인할 수 있게 한다.

토스페이 API

토스는 결제 상태, 결제 결과 callback, 가맹점 승인, 결제 환불, 결제 상태 확인 등의 API를 오픈소스로 깃허브에 공개해두었다.

다른 소프트웨어의 기능 실행

API는 다른 소프트웨어의 기능을 호출하고 실행할 수 있는 방법을 제공한다. 이를 활용하여 애플리케이션은 다른 애플리케이션의 기능을 활용하여 복잡한 작업을 간편하게 수행할 수 있다.

결제가 필요한 애플리케이션의 카카오페이, 네이버페이 및 PG 사는 API를 활용해서 결제 시스템을 구축했다.

카카오페이 | 개발자센터

네이버페이 개발자센터

서비스 접근

웹 서비스나 클라우드 서비스에 접근할 수 있는 방법을 제공한다. 개발자는 다양한 서비스를 사용하여 애플리케이션 기능을 간편하게 확장할 수 있고, 성능을 개선할 수 있다.

클라우드 서비스의 시장 점유율이 가장 높은 AWS는 API로 제공하는 서비스를 액세스할 수 있게 제공하고 있다.

AWS API 호출하기 (1) – 개론편 | Amazon Web Services

2. REST 🗨️

REST란 무엇일까?

REST(Representational State Transfer)는 네트워크 상에서 자원을 정의하고 접근하는 방식을 정하는 아키텍처 스타일이다. HTTP 프로토콜을 기반으로 하여 클라이언트와 서버 간의 상호작용을 정의
한다
Restful API는 이러한 REST 원칙을 따르는 API를 의미한다.

REST란 자원을 이름으로 구분하여 해당 자원의 상태(정보)를 주고 받는 것이다. 즉, 자원(resource)의 표현(representation)에 의한 상태 전달이다.

자원은 해당 소프트웨어가 관리하는 이미지, 데이터 등을 의미하고 자원의 표현은 예를 들어 DB의 학생 정보가 자원일 때, ‘students’를 자원의 표현으로 정하는 것이다.

REST의 구체적인 개념

HTTP URL을 통해 자원을 명시하고, HTTP 메소드를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다. CRUD란 REST API를 설계할 떄 기본적인 기능을 정의하는 것이다.

CRUD Operation & HATEOAS

CRUD란 Restful API의 기능 설계와 비슷한 개념이다. 사용자의 컴퓨터에서 동작하는 서비스, 기능 등을 만들기 위한 기초가 되는 기능들을 설계할 때 사용한다.

CRUD

Create : 생성(POST)
Read : 조회(GET)
Update : 수정(PUT)
Delete : 삭제(DELETE)
HEAD : header 정보 조회(HEAD)

CRUD의 관점에서 봤을 때, 예시로 사용자가 로그인하는 상황이라고 가정하자. 그럼 이는 Create에 해당된다. 사용자의 정보를 확인하는 것은 Read, 사용자가 정보를 수정하는 것은 Update, 사용자가 회원탈퇴하는 것은 Delete에 해당된다.

HATEOAS(Hypermedia As the Engine of Application State)

REST API의 HATEOAS는 웹페이지의 하이퍼 링크와 같다. 서버와 클라이언트를 분리하여 Restful 웹 서비스에서 자원의 상태를 하이퍼미디어를 통해 제어하는 것을 의미한다. REST 아키텍처의 중요한 개념 중 하나이다.

개발자는 클라이언트 중단에 대해 걱정하지 않고 API를 업데이트하고 발전시킬 수 있다.

REST의 6️⃣원칙

REST의 창시자인 로이 필딩(Roy Fielding)은 REST 아키텍처를 정의하기 위해 6가지 주요 원칙을 제시했다.

클라이언트- 서버 구조	클라이언트와 서버는 서로 독립적인 역할을 수행하며, 클라이언트는 사용자 인터페이스와 사용자 경험을 관리하고 서버는 데이터 저장 및 비즈니스 로직을 처리한다.
무상태성(Statelessness)	모든 요청은 독립적이며, 서버는 클라이언트의 상태를 저장하지 않는다. 각 요청은 필요한 모든 정보를 포함해야 한다.
캐시 가능(Cacheable)	응답은 캐시될 수 있어야 하며, 클라이언트는 서버로부터 데이터를 다시 요청하지 않고도 응답을 재사용할 수 있어야 한다.
통합 인터페이스(Uniform Interface)	클라이언트와 서버 간의 상호 작용을 일관성 있게 정의하여, 시스템 전체의 인터페이스가 표준화된다.
계층화 시스템(Layered System)	클라이언트는 중간 계층(ex: 프록시, 게이트웨이)을 통해 서버에 접근할 수 있으며 이러한 계층은 시스템의 확장성과 보안을 향상시킨다.
코드 온 디맨드(Code on Demand)	서버는 클라이언트에게 코드를 전송하여 클라이언트가 이를 실행할 수 있다.(선택적)

REST의 장단점

| 장점 | - HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구축할 필요가 없다.

자원의 상태를 전송하기 위해 간단한 HTTP 메서드를 사용한다.
무상태성으로 인해 서버 확장이 용이하다.

JSON, XML 등 다양한 데이터 형식을 지원해 다양한 클라이언트와 쉽게 통신이 가능하다.
단점	- 각 요청이 독립적이기 때문에 클라이언트의 상태를 유지해야 하는 애플리케이션에서는 추가적인 구현이 필요하다.

여러 요청이 필요한 복잡한 트랜잭션을 처리하기 어렵다.
HTTP 헤더와 상태 정보를 포함한 추가적인 데이터 전송으로 인해 오버헤드가 발생할 수 있댜.
표준화된 명세가 부족할 수 있다. |

3. REST API 🔌

REST API(Restful API)는 REST 아키텍처 스타일의 설계 원칙을 준수하는 API이다. 애플리케이션을 통합하고 마이크로서비스 아키텍처의 구성 요소를 연결하는 유연하고 가벼운 방법을 제공한다.

REST API의 작동 원리

자원(Resource)

웹에서 접근할 수 있는 모든 항목(데이터, 서비스) 고유한 URL로 식별
ex ) /users, /users{id}, /products, /products/{id}

HTTP 메소드

REST API는 HTTP 메소드를 통해 통신하여 리소스 내에서 레코드를 CREATE하고 READ, UPDATE 및 DELETE(CRUD)와 같은 표준 데이터베이스 기능을 수행한다.

GET	자원 조회
POST	새로운 자원 생성
PUT	기존 자원의 업데이트
DELETE	자원의 삭제
PATCH	자원의 부분 업데이트

표현(Representation)

자원의 데이터는 JSON, XML 형식으로 표현. 클라이언트는 이러한 표현을 통해 자원과 상호작용

HTTP 상태 코드(HTTP Status Code)

서버는 클라이언트의 요청에 대한 응답으로 HTTP 상태 코드를 반환한다.

ex) 2xx : 성공, 4xx : 클라이언트 에러, 5xx : 서버 에러

헤더(Header)

HTTP 헤더는 요청 및 응답에 대한 메타데이터를 포함한다.

ex) ‘Content-Type’ 헤더는 요청 또는 응답의 데이터 형식을 나타낸다.

좋은 REST API란? 👍

좋은 REST API는 설계와 구현에 있어서 클라이언트와 서버 간의 상호작용을 효율적으로 일관되게 만들어준다. 클라이언트와 서버 개발자 간에 소통 문제로 잘못된 상태 코드를 생성한다던가, 잘못된 요청을 하지 않도록 상호 간의 협의를 통해 설계하는 것이 중요하다.

그렇다면 좋은 REST API를 설계하기 위해선 어떻게 해야할까?

자원의 명확한 URL 설계

URL은 일관성 있고, 의미 있는 방식으로 명확하게 설계해야 한다.

예를 들어서 유저 정보를 검색하는 기능을 API로 설계한다고 가정해보자. /peachpeach라고 URL을 정의한다면 누군가가 알아볼 수 있을까? 전혀 알아볼 수 없을 것이다.

따라서 /users와 같은 명사로서 간결하고 명확하게 표현하는 것이 좋다.

(개인의 상세정보 같은 경우에는 /user/userindex의 형태로 사용하는 것이 좋다.)

상태 코드를 적절히 사용하기

API 요청에 대해 응답할 떄는 항상 HTTP 상태 코드를 포함해 요청과 응답이 명확하게 처리되도록 해야한다.

200	요청이 성공적으로 처리
201	새로운 자원이 성공적으로 생성
204	요청이 성공적으로 처리되었지만 반환할 데이터가 없을 때
400	잘못된 요청일 때
401	인증이 필요할 때
403	접근 권한이 없을 때
404	자원을 찾을 수 없을 때
500	서버에서 오류가 발생했을 때