REST API에 대해서 들어본 적 있는가. 클라이언트, 프론트엔드, 백엔드에 상관없이 개발자라면 꼭 알고 있어야 할 REST API에 대해서 알아보자.
실제로 필자가 예전에 회사에서 REST API를 접한 적이 있었는데, 당시에 설명을 아무리 읽어봐도 완벽하게 이해하기 힘들었다. 지금 설명해 보라고 하면 솔직히 자신없다.. 그래서! 이번에 제대로 알고 설명할 수 있을 정도로 머리에 세겨보려고 한다.
1. REST API가 뭐지?
REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다.
위키백과에 이렇게 설명되어 있는데 도통 무슨 말인지 모르겠다. 그래서 유튜브에 REST API에 대한 영상을 찾아봤는데, 얄팍한 코딩사전 : REST API가 뭔가요? 이 영상이 이해하기 쉬웠다.
REST API는 정보들이 주고받아지는 데 있어서 개발자들 사이에 널리 쓰이는 일종의 형식이다.
위의 영상에서 REST API를 이렇게 정의하는데, 확실히 위키백과보단 이해가 된다. REST API는 어떤 데이터가 전달되는데 사용하는 일종의 형식이다.
2. 우선, API에 대해 알아보자.
API(Application Programming Interface)는 소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청, 명령을 받을 수 있는 수단이다.
예를 들어, 날씨 관련 서비스를 제공하는 웹사이트, 앱이 기상청 서버로부터 실시간으로 날씨정보를 요청할 때, 미리 작성된 소프트웨어를 통해서 기상청 서버와 서버들 또는 앱 사이에 정보들이 요청되고 전송되는 것이다.
원하는 정보를 받아오려면 지정된 형식에 맞춰 기상청 서버에게 정보를 요청해야 한다. 날짜, 지역, 조회할 내용을 포함한 주소로 정보를 받을 수 있다는 공개된 메뉴얼을 참고해서 누구든지 기상청 정보를 활용한 소프트웨어를 만들 수 있다. 이게 바로 API다.
네트워크 상에만 API가 있는 것은 아니다. 브라우저는 Web API를 통해서 자바스크립트로부터 특정 동작들을 지시받기도 하고, 윈도우에는 Windows API를 참고하여 시스템이나 하드웨어에 대한 지식이 부족해도 윈도우 소프트웨어를 개발할 수 있다.
3. REST API에 대해서 자세히 알아보자.
웹에서 서버로 데이터를 요청하거나 배달 앱에서 서버에 주문을 넣거나 등 이런 서비스들에서 오늘날 널리 사용되는 것이 REST 형식의 API이다. REST의 가장 중요한 특징은 각 요청이 어떤 동작이나 정보를 위한 것인지 추론 가능하다는 것이다.
만들고자 하는 서비스에서 기능 자체만 중요하게 생각한다면 REST API는 생각할 필요 없이 동작만 하게 만들면 그만이다. 이게 무슨 말인지 아래 예시를 살펴보자.
어떤 학원의 반과 학생들에 대한 API를 만든다고 가정해 보자.
주소 끝에 1을 붙이면 반들의 리스트를,
hello를 붙이면 학생들 리스트를,
학생 이름을 붙이면 학생 정보 수정을 요청하는 API이다.
이런 식으로 구현해도 서비스 기능 자체에는 문제가 없겠지만, 문제는 서비스를 이 개발자 혼자 만드는 게 아니라는 것이다. 당장은 혼자라도, 나중에 이 일을 인계받을 개발자나 이 API를 사용해서 다른 제품을 만들 개발자들은 굉장히 일하기 힘들어질 것이다.
"RESTful 하게 만든 API는 요청을 보내는 주소만으로도 대략 이게 뭘 하는 요청인지 파악이 가능하다."
학원 데이터베이스에 정보를 요청을 할 때 주소에 classes가 붙는다면 아마도 학원의 반들 목록을 받아오는 요청일 것이다.
그 뒤에 이렇게 고유번호가 따라붙으면 보통은 그 반들 중 인덱스 번호에 해당하는 반의 정보가 온다.
그 뒤에 students를 붙여서 보내면 이 반에 해당하는 학생들의 정보가,
여기에 또 idx를 붙이면 그 학생들 중 이 인덱스 번호를 가진 학생의 정보가 올 것이다.
이렇게 조건을 붙여서 남학생들의 정보만 받아올 수도 있다.
한 페이지에 10명씩 받아오는 거라면 이런 식으로 표현할 수도 있다.
CRUD와 HTTP 메서드
자원을 구조와 함께 나타내는 이런 형태의 구분자를 URI라고 한다. 그런데 이런 조회 작업뿐 아니라, 정보를 새로 넣거나 수정하거나 삭제하는 작업도 필요하는데 이를 통틀어서 CRUD라고 한다.
서버에 REST API로 요청을 보낼 때는 HTTP 규약에 따라 신호를 전송한다. 우체국에서 뭘 부칠 때 일반우편, 등기, 택배 등 다양한 방식이 있듯이 이 HTTP로 요청을 보낼 때도 여러 메서드가 있다.
REST API에서는 주로 아래 4가지 혹은 5가지를 사용한다. post, put, patch에는 body라는 주머니가 있어서 get이나 delete보다 정보들을 많이, 비교적 안전하게 감춰서 실어 보낼 수 있다.
post 하나로 데이터를 쓰고 읽고 수정하고 지우기까지 할 수 있지만, 누구든 각 요청 의도를 쉽게 파악할 수 있도록 RESTful 하게 API를 만들기 위해서는 이들을 목적에 따라 구분해서 사용해야 한다.
GET 메서드는 데이터를 조회할 때 사용한다. 아래 URI에 get으로 보내는 요청이 있다면 개발자들은 '아, 이 반의 학생들을 조회하는 요청이구나.' 하고 짐작할 수 있다.
POST는 새로운 정보를 추가할 때 사용한다. 아래와 같이 URI를 작성하고 post 요청으로 body에 새 학생의 정보를 실어 보내면 새로운 학생의 정보가 추가된다. 학생의 idx는 보통 정보가 추가되면서 생성되기 때문에 post 요청에서 명시하지 않아도 된다.
정보를 변경할 때는 URI에 변경할 학생의 idx까지 명기한 다음 put 또는 patch로 변경할 새 정보를 body에 실어 보낸다. 보통 put은 정보를 통째로 변경할 때, patch는 정보의 일부를 변경할 때 사용한다.
DELET는 정보를 삭제할 때 사용한다. URI에 학생의 idx까지 표시해 주면 해당 학생의 정보가 삭제된다.
REST 규칙
앞서 말했듯이 post나 put 하나로도 용량이 작고 중요도가 낮은 정보들은 CRUD를 구현할 수 있지만, 구분 가능한 요청을 만들려면 URI에 동작까지 명시해야 한다.
이것을 지양하기 위한 REST의 규칙 중 하나는 URI는 동사가 아닌 명사로 이뤄져야 한다는 것이다.
결국 REST API란, HTTP 요청을 보낼 때 어떤 URI에 어떤 메서드를 사용할지 개발자들 사이에 널리 지켜지는 약속이다. 형식이기 때문에 기술에 구애받지 않는다.
어떤 언어로 사용하든 소프트웨어 간에 HTTP로 정보를 주고받는 부분이 있다면 이 형식과 규칙들을 준수해서 RESTful 한 서비스를 만들 수 있다.
오늘 알게 된 내용들은 RESTful API의 아주 기초적인 내용이고, 인터넷에 아래 "restful api design guidelines"를 검색하면 보다 자세한 내용들을 찾아볼 수 있을 것이다.
💙 참고한 영상 💙
