API(1) - API란 무엇인가

안녕하세요. 저번주까지는 햇빛이 쨍쨍하니 예쁜 날이 지속되었는데, 이번주는 월요일부터 날이 흐리네요. 갑자기 추워진 것 같아요.

저번 시간에는 인덱스와 작동원리를 마지막으로 더 깊은 데이터베이스의 지식에 대한 얘기를 끝냈습니다. 이번에는 API에 대해서 5편에 나눠서 얘기할 것 같습니다.

 

---

API

application Programming Interface의 약자로, 한 프로그램에서 다른 프로그램으로 데이터를 주고 받기 위한 방법이다. 즉, 서로 다른 소프트웨어가 정해진 방식으로 기능을 요청하고, 그 결과를 주고 받을 수 있도록 만든 인터페이스입니다.

 

API를 이해하기 위해서는 먼저 클라이언트와 서버가 어떤 방식으로 통신하는지 살펴볼 필요가 있습니다.

 

클라이언트와 서버 통신

클라이언트와 서버의 통신은 기본적으로 요청(Request)과 응답(Response)으로 이뤄집니다.

클라이언트가 서버에 GET /user/age 요청을 보내 사용자 나이 정보를 요청하고, 서버는 이를 처리한 뒤 age : 20 이라는 결과를 응답합니다.

즉, 클라이언트는 필요한 데이터를 서버에 요청하고 서버는 그 결과를 반환하며, 이러한 요청과 응답이 정해진 방식으로 이루어지도록 돕는 것이 API입니다.

 

그렇다면 이러한 API를 설계하는 대표적인 방식 중 하나가 REST입니다.

 

REST

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

즉, HTTP URI를 통해 자원을 명시하고, HTTP 메서드를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미합니다.

 

이러한 REST를 이용하여 API로도 적용시킵니다.

REST API

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

그렇다면 API를 RESTful하게 설계하는 것은 구체적으로 어떤 의미일까요?

 

RESTful

API가 REST의 설계 원칙을 잘 반영하고 있다는 의미입니다. 즉, 자원은 URI로 표현하고, 행위는 HTTP 메서드로 구분하며, 클라이언트와 서버의 역할을 명확히 나누어 일관성 있게 설계한 상태를 의미합니다.

 

그렇다면 왜 RESTful하게 설계해야할까요?

RESTful하게 설계하는 이유 

RESTful하게 설계하면 API의 목적과 구조를 더 쉽게 파악할 수 있기 때문입니다. 

자원을 중심으로 URI를 설계하고, 행위는 HTTP 메서드로 구분하기에 요청의 의미가 명확해집니다.

또한 이러한 일관성은 프론트엔드와 백엔드 간 협업을 수월하게 하고, 추후 기능이 추가되거나 수정될 때도 유지보수에 유리하기 때문입니다.

 

즉, RESTful한 설계는 API를 더 읽기 쉽고, 이해하기 쉽고, 관리하기 쉽게 만들어 줍니다.

 

RESTful한 경우와 그렇지 못한 경우를 예시로 들어봅시다.

 

RESTful한 URI와 그렇지 않은 URI

1. 조회할 경우

나쁜 예	좋은 예
GET /getUser/1	GET /users/1
- getUser는 동작이 URI에 들어가 있다. - REST에서는 자원인 users를 URI에 둔다.

2. 삭제할 경우

나쁜 예	좋은 예
POST /deleteUser/1	DELETE /users/1
- deleteUser는 삭제하는 동작/행위가 URI에 포함되어 있다. - DELETE(생성)이 아닌 DELETE 메서드로 표현해야한다.

 

이 외에도 수정, 생성할 경우에도 마찬가지 RESTful하게 API를 설계해야한다.

 

그렇다면 API를 설명하는 과정에서 계속 등장했던 GET, POST와 같은 표현은 무엇일까요?

 

HTTP 메서드

클라이언트가 서버에 어떤 작업을 요청하는지를 나타내는 방식입니다.

RESTful한 API에서는 URI로 자원을 표현하고, HTTP 메서드로 그 자원에 대한 행위를 구분합니다.

 

1. GET
   • 서버에 저장된 데이터를 조회할 때 사용하는 HTTP 메서드
   • 클라이언트는 특정 자원에 대한 정보를 요청하고, 서버는 그 결과를 응답으로 반환합니다.
   • 예를 들어 GET /users/1은 1번 사용자의 정보를 조회하는 요청입니다.
2. POST
   • 새로운 데이터를 생성할 때 사용하는 HTTP 메서드
   • 클라이언트가 서버에 데이터를 전달하면, 서버는 이를 처리하여 새로운 자원을 생성합니다.
   • 예를 들어 POST /users는 새로운 사용자를 등록하는 요청으로 볼 수 있습니다.
3. PUT
   • 기존 데이터를 전체 수정할 때 사용하는 HTTP 메서드
   • 특정 자원의 모든 내용을 새 데이터로 교체하는 방식입니다. 
   • 값이 변경되는 과정에서 NULL 또는 빈 값으로 변경될 수 있습니다.
   • 예를 들어 PUT /users/1은 1번 사용자의 정보를 전체적으로 수정하는 요청입니다.
4. PATCH
   • 기존 데이터의 일부만 수정할 때 사용하는 HTTP 메서드
   • 전체 데이터를 다시 보내는 것이 아니라, 변경이 필요한 부분만 전달하여 수정합니다.
   • 예를 들어 PATCH /users/1은 1번 사용자의 이메일,이름 등 일부 정보만 변경하는 요청입니다.
5. DELETE
   • 특정 데이터를 삭제할 때 사용하는 HTTP 메서드
   • 클라이언트가 삭제할 자원을 지정하면, 서버는 해당 자원을 제거합니다.
   • 예를 들어 DELETE /users/1은 1번 사용자 정보를 삭제하는 요청입니다.

---

오늘은 이렇게 API에 대해서 정리해보았습니다. 예전에 작성했던 블로그 글 중에 HTTP에 대해서 메서드와 내용을 아주 짤막하게 정리를 했었는데, 이번 편이 그 내용에 대한 보충이 되겠네요. 

다음 시간에는 API 데이터 형식 중 JSON API에 대해서 알아보도록 하겠습니다. 수고하셨습니다.