RESTful API

Haz·2024년 5월 9일

개발여행기

목록 보기

22/25

이제는 익숙한 그 이름, RESTful API.
어느 채용공고에서나 흔하게 보이는 조건 중 하나가 되었다. 내가 개발을 시작했을 때는 이미 거의 대세로 자리잡은 상황이었기 때문에 이게 왜 이렇게 각광 받는지는 모른 채로 써야한다니까 쓰는 API 형식이었다.
하지만 이제 모른 채로 "쓰라니까 쓰는 건데요??" 하면 "그러고도 당신이 개발자냐!" 소리 듣기 딱 좋다😓!

가볍게 RESTful API가 뭐길래 대세가 됐는지, 왜 쓰는지 정리해보자.

REST API

RESTful API?

RESTful API가 오프라인에서 이뤄진다면

API란 자고로 무엇이냐. 주민센터에 가서 등본을 발급받고 싶은 상황이라고 생각해보자.

🅰️: 내가 이 나라 사람인지 등본 떼서 확인하고 싶어.
🅱️: 그럼 이 형식에 맞춰서 요청하고 본인인지 확인되면 당신이 이 나라 사람이라는 증명인 주민등록등본을 내가 떼주지.

오프라인이라면 이렇게 말과 글로 소통하겠지만, 개발자들의 언어는 코드이기 때문에 이런 과정을 정리한 게 바로 API라는 거다.

마치 등본을 발부 받기 위한 신청 양식이 있는 것처럼 양쪽이 쉽고, 빠르고, 편하게 코드로 소통하기 위해 정해둔 형식이기 때문에 당연히 알아보기 쉽고 사용하기 편할수록 좋다.

태초에 여러 가지 API 형식이 있었으나, RESTful API는 웹에서의 범용성을 토대로 유용함을 인정 받은 형식이기 때문에 이렇게 널리 사용되고 있는 것이다. 이 형식의 중요한 특징 두 가지는 아래와 같다.

URL 정보의 자원을 표현해야 한다.

자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

출처: https://blog.jgtradeplus.com/1-api%EC%9D%98-%EC%9D%B4%ED%95%B4/

즉, HTTP 기반으로 우리가 필요한 CRUD를 만들도록 하는 API 형식인 셈이다.

RESTful한 요청 서식

그렇다면 등본 발부 양식, 그러니까 RESTful한 요청은 어떻게 보내야할까?

방법은 총 5가지다.

POST: 새 데이터 추가
GET: 데이터 가져오기
PUT: 데이터 수정
PATCH: 데이터 상태 변경
DELETE: 데이터 삭제

그리고 이 요청들을 위에서 이미 언급한 대로 URL을 통해 작성하는 방식이다. 참으로 놀랍게도 URL은 전역 상태이자 변수이기 때문에 특히 클라이언트와 서버 간 요청을 보내기 아주 좋은 수단이다.

이거에 대한 건 다른 글에서 좀 더 자세히 다뤄보고, 어쨌든 중요한 건 요청 방법은 GET, POST, PUT, PATCH, DELETE 5가지고 이걸 URL 형식에 맞춰 HTTP 요청을 보내는 게 RESTful한 API라는 것이다. 이 중에서도 PUT, PATCH는 비슷한 동작을 수행하지만 전체를 수정하는지, 부분을 수정하는지 정도의 차이를 가지고 있다. 일부 데이터만 수정하고 싶다면 PATCH를 사용하면 된다.

❗ 사실 HTTP는 RESTful API의 필수 요소는 아니다. 그렇지만 웹 개발자들에게 무엇보다 익숙한 프로토콜이고, RESTful API의 조건에 맞춰 활용하기에도 적합하기 때문에 주로 사용한다.

그럼 요청하고 응답 받을 데이터는 서식에 맞춰서 어떻게 작성해야할까?

[
  {
  	"id": 1,
    "title": "RESTful API",
    "author": "Haz",
    "published_date": "2024-05-01"
  },
  {
  	"id": 2,
    "title": "CRUD",
    "author": "Haz",
    "published_date": "2024-05-09"
  },
]

이처럼 요청과 응답에는 구조화된 표현이 쉽고 가벼운 JSON을 활용한다.

CRUD와 RESTful API

결국 우리가 API 요청을 보내는 이유는 CRUD를 구현하고 싶어서다. 데이터를 기반으로 Create, Read, Update, Delete 기능을 구현해서 결과적으로 원하는 애플리케이션을 만들게 되는데 RESTful API의 방법과 CRUD를 어떻게 연결지을 수 있을까?

CREATE ➡️ POST

READ ➡️ GET

UPDATE ➡️ PUT

DELETE ➡️ DELETE

아무래도 기능 구현에 필수적인만큼 위 네 가지가 가장 흔하게 자주 쓰게되는 RESTful API 요청 방법이다. 예시를 살펴보자.

https://velog.io/write?id=192948

우리가 흔하게 보는 URL이다. 뜯어보면 https://(http://) HTTP 프로토콜을 사용하고 있고, 뒤에 URI를 통해 필요한 자원이 뭔지 전달하고 있다는 걸 알 수 있다.

하지만 URI만 보면 이게 GET 요청인지, POST 요청인지 도대체가 알 수가 없다. 하지만 이게 바로 핵심이다. URI는 가능하다면 요청이 어떤 자원에 관한 것인지만 표현해야한다. 무엇을 할 지는 요청을 보낼 때 HTTP 메소드 종류로 구별하면 되기 때문이다.

상상력을 살짝 발휘해보면 무슨 작업을 하는 요청인지 URL을 통해서 보냈을 때 발생할 문제를 쉽게 떠올릴 수 있다. 우리 모두가 사랑하는 유튜브에서 URL로 GET 요청만 보낼 수 있는 게 아니라 DELETE 요청도 보낼 수 있다고 상상해보자. 누군가 이를 악용해서 동영상을 지우는 요청 테러를 보낸다면 어떨까? 상상만 해도 끔찍하다. 결국 이는 보안과도 연관된 중요한 문제다.

URI를 좀 더 나누어서 살펴보면 /write으로 velog.io DB에 수많은 정보 중에 write에 관련된 정보만을 1차적으로 가져오고 ?id=192948 쿼리스트링으로 2차적으로 필터링을 해서 HTTP 요청을 수행하게 된다. 일반적으로 페이지, 한 페이지에 보여줄 정보량 등을 담기도 하고 광고에 필요한 매체 정보들을 담기도 한다.

성공했어? 실패했어?

요청을 보내고 응답이 올 때 가장 심장이 뛰는 순간이 찾아온다. 내가 작성한 요청서가 형식을 잘 맞췄는지 확인 받는 순간이다.

미리 상황에 따라 성공인지 실패인지 정해둔 Status Codes가 있다. 보통 성공했을 때 받는 코드 번호는 200이다. 백의 자리가 '2'라면 성공했다는 코드이기 때문에 환호성 한 번 질러주고 응답 받은 데이터로 신나게 작업하면 된다.

그렇지만 그외의 경우에는 이제 전쟁이 시작된다. 실패 코드는 400번대, 500번대가 대부분이다. 백의 자리가 '4'인지 '5'인지에 따라 책임 소재가 갈리기 때문에(?) 긴장되는 순간이 아닐 수 없다.

4XX로 응답 코드가 왔다면 그건 클라이언트 쪽에서 서식을 잘못 작성한 것이다. 사용자가 가장 흔하게 보게 되는 클라이언트 에러는 그 유명한 404, 즉 페이지가 없다는 에러다. 그외에도 권한 외 요청을 했을 경우 등에도 해당 응답 코드를 받아볼 수 있다.

5XX로 응답 코드가 왔다면 서버 쪽에서 에러가 발생한 경우다. 502, 503 같은 에러 코드는 가끔 사용자도 볼 수 있는 에러인 게이트웨이 오류, 서버 과부하로 인한 다운 등의 경우다.

자세한 응답 코드는 정리가 잘 되어있는 이 블로그를 참고해보자.

개발자만 알고 있어도 될 응답 코드도 있지만, 사용자가 알아야할 응답 오류인 경우도 있기 때문에 이에 대응할 수 있는 페이지 개발도 필수적이다.

Stateless한 RESTful API

RESTful API에서 서버는 클라이언트의 요청을 기억하지 않아야한다. 우리 생활 속에서 찾아보자면 서버는 말하지 않으면 집에서 아무것도 하지 않고 소파에서 누워만 있는 수동적인 사람이고 클라이언트는 양말 뒤집어 놓지 말라는 말을 수도 없이 해야만 하는 사람이다. 서버가 실제 사람이라면 속터지기 일보 직전이겠지만, 다행히 서버는 사람이 아니기 때문에 클라이언트 속도 뒤집어놓지 않는다.

비유한 것처럼 서버는 요청을 그간의 요청을 절대 기억하지 못하기 때문에 클라이언트는 직전 요청과 같은 내용을 요청한다 할지라도, 필요한 내용을 모두 매번 포함시켜 보내야한다.

이는 멱등성과도 연결되어 클라이언트가 같은 요청을 보낼 경우 반드시 동일한 응답이 오도록 해야 하기 때문이다.

하지만 매번 이러면 서버와 클라이언트는 괜찮겠지만 반복 작업을 실질적으로 하는 개발자들의 속은 타들어갈 것이다. 이를 위해서 어떤 요청을 보냈고, 어떤 응답을 받았는지 한 번 얻어낸 데이터를 저장해 쓸 수 있도록 도와주는 도구가 있으니 그것이 바로 "캐싱"이다.

클라이언트에서 한 요청에 받은 응답을 캐싱해두면 같은 작업을 반복하지 않아도 되고 개발자의 정신 건강도 챙길 수 있게 된다. 서버 또한 마찬가지다.