REST API

페리·2021년 4월 19일

REST API에 대해 궁금증이 생겨 찾아보게 되었다.
참고한 자료는

유튜버 '얄팍한 코딩사전'의 "REST API가 뭔가요?"

라는 영상이었다.
평소에 이 분의 영상이 쉽게 이해되어 좋았는데, "REST API"에 대해서도 설명해주신 영상을 발견하여 그대로 정리해보게 되었다.

먼저 밝혀둘 것은, 이 영상에서 알려드릴 것은,

진정한 의미의 REST API가 무엇인가?

가 아니라 개발자들이 '일반적으로' 알고 쓰는 수준의 REST API입니다.

도미노나 피자에땅같은 피자가 뭔지 알려드리는거지, '그런 건 피자가 아니야!' 하고 화내는 이탈리안 주방장이 현지에서 만드는 정통 로컬 피자가 아니라는 이야기말입니다.

이미 REST API란 게 뭔지 아시는 분들은, 학술적으로 정확한 의미의 REST API를 알고자 하신다면

그런 REST API로 괜찮은가

라는 키워드로 검색해보시면, 어떤 분이 굉장히 잘 설명해주신 영상을 찾아보실 수 있을 것입니다.

REST API는 정보가 주고받아지는 형식에 있어서 개발자들 사이에 널리 쓰이는 일종의 형식입니다.

우체국에 가면 이러한 송장들이 있고,

이용자들은 그것들의 정보를 채워넣는 것처럼요.

어떤 기술이나 제품이 아니라, 형식이기 때문에 여러분이 어떤 프레임워크를 쓰든, 뭐에다 소프트웨어를 만들든 이 폼에 맞춰서 기능을 만들어내면 되는 거죠.

일단 API란게 뭔지부터 알아보기로 해요.

어떤 기계를 만들면, 사용자가 그 기계를 전부 사용할 수 있도록, 제어장치를 마련해야 해요.

예를 들어, TV는 사용자가 그걸 켜거나 끄고, 채널을 선택하고 음량을 조절할 수 있게 해주어야 하죠.

그래서 리모컨이 있는 거에요.

같은 이유로 자판기에는 버튼들이 있고, 컴퓨터에는 키보드와 마우스가 있죠.
이런 것들을 인터페이스라고 불러요. 기계와 인간 간의 소통 창구인 거죠.

사용자가 명령을 넣는 것 뿐 아니라, 그 결과와 정보들을 받아오기 위한 TV의 스크린, 컴퓨터의 모니터 또한 이 인터페이스에 속해요.

소프트웨어의 영역으로 들어가볼까요?

컴퓨터나 스마트폰을 켜보면 사용자들이 프로그램이나 사이트, 앱을 원하는대로 제어하고 정보를 볼 수 있도록 버튼, 스크롤바, 슬라이더, 브라우저 창 등 소프트웨어적인 장치들이 마련되어있죠?

UI란 말 많이 들어보셨을 거에요.
소프트웨어와 인간의 소통을 위한 User InterFace인거에요.

하지만 IT 세계에서는 우리 눈에 직접 보이지 않는 영역들이 더 많죠.
기계와 기계, 소프트웨어와 소프트웨어 사이에도 수많은 요청과 정보 교환이 이뤄지고 있어요.

이들 사이에도 소통할 수 있는 창구가 필요한 거죠.

기상정보가 관리되는 기상청 서버가 있어요. 포털이나 기타 날씨에 관련된 서비스를 제공하는 다양한 웹사이트들, 앱들이 이 기상청 서버로부터 실시간으로 날씨정보를 요청해서 받아가요.

미리 작성된 소프트웨어를 통해서 이 기상청 서버와, 이 서버들 또는 앱들 사이에 정보들이 요청되고 전송되는 거죠.

그렇다면 이 기상청 서버에게 정보들을 요청하는 지정된 형식이 있어야겠죠. 여기에 "날짜, 여기에 지역, 여기에 조회할 내용" 이렇게 표시해서 이 주소로 정보를 요청하면 이렇게 답이 올거라는 공개된 메뉴얼이 있으면 누구든 이걸 참조해서, 기상청 정보를 활용하는 소프트웨어를 만들 수 있을 거에요.

이처럼 소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청, 명령을 받을 수 있는 수단을

Application Programming Interface

API라고 해요.

꼭 네트워크 상에만 API가 있는 것이 아니에요.
이 영상에서 언급했듯, 로컬 프로그램인 브라우져는 Web API를 통해 자바스크립트로부터 특정 동작들을 지시받기도 하죠.

윈도우에는 개발자들이 프로그램을 개발할 때 시스템이나 하드웨어에 대한 세세한 지식 없이도 지정된 명령어로 윈도우에서 동작을 수행하도록 소프트웨어를 짤 수 있는 Windows API를 제공해요.

'이 함수를 넣으면 윈도우가 이렇게 해 준다'는 걸 알면 개발자는 그 명령어들로 코드를 짜면 되는거죠.

이제 API란게 뭔지는 분명히 이해가 되셨을 거에요.

그럼 이제 그 중에서 REST API가 뭔지 알아보죠.

예전 영상에서 다뤘던 Vue 예제처럼 프론트엔드 웹에서 서버에 데이터를 요청하거나 배달 앱에서 서버에 주문을 넣거나 등 이런 서비스들에서 오늘날 널리 사용되는 것이 REST란 형식의 API에요.

과거의 SOAP이란 복잡한 형식을 대체한거죠.

REST의 가장 중요한 특성은 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론 가능하다는 거에요.

사실 만들고자 하는 서비스에서 기능 자체만 중요하게 생각한다면 REST고 뭐고 생각할 필요 없이 동작만 하게 만들면 그만이죠.

어떤 학원의 반과 학생들에 대한 API를 만들 때,
이 주소 끝에 1을 붙이면 반들의 리스트, hello를 붙이면 학생들의 리스트, hyot-hong를 붙이면 담아진 내용대로 학생 정보 수정을 한다던지

이런 식으로 짜도 이에 맞춰 요청을 보내는 앱을 짜면 서비스의 기능 자체에는 아무런 문제가 없을 거에요.

문제는 서비스를 이 개발자 혼자 만드는 게 아니란거죠.

당장은 혼자라도, 나중에 이 일을 인계받을 개발자나, 이 API를 사용해서 다른 제품을 만들 개발자들은 굉장히 일하기 힘들어질 거에요.

RESTful하게 만든 API는 요청을 보내는 주소만으로도 대략 이게 뭘 하는 요청인지 파악이 가능해요.

학원 DB에게, 정보를 보내달라는 요청을 할 때
주소에 이렇게 classes가 붙는다면 아마도 학원의 반들 목록을 받아오는 요청일거에요.

그 뒤에 이렇게 idx, 고유번호가 따라붙으면 보통은 그 반들 중 인덱스 번호가 이 숫자인 반의 정보가 오죠.

그 뒤에 students를 붙여서 보내면 이 반에 해당하는 학생들의 정보가, 여기에 또 idx를 붙이면 그 학생들 중에 이 인덱스 번호를 가진 학생으 정보가 오겠죠.

혹은 이렇게 조건을 붙여서 남학생들의 정보만 받아올 수도 있을 거에요.

한 페이지에 10명씩 받아오는 거라면 이런식으로 표현이 가능하고요.
git똥차죠?

자원을 구조와 함께 나타내는 이런 형태의 구분자를 URI라고 해요. 그런데 이런 조회작업 뿐 아니라, 정보를 새로 넣거나 수정하거나 삭제하는 작업도 필요하죠. 이들을 통틀어서

C. Create
R. Read
U. Update
D. Delete

CRUD라고 불러요.

서버에 REST API로 요청을 보낼 때는

HTTP : HyperText Transfer Protocol

이란 규약에 따라 신호를 전송해요.

우체국에서 뭘 부칠 때 일반우편, 등기, 택배 등 다양한 방식이 있듯이 이 HTTP로 요청을 보낼 때도 여러 메소드가 있어요.

REST API에서는 이 4가지 혹은 5가지를 사용하죠.

소포가 편지보다 더 많은 걸 담을 수 있듯이, post, put, patch에는 body란 주머니가 있어서,
정보들을 get이나 delete보다 많이, 그리고 비교적 안전하게 감춰서 실어보낼 수 있어요.

사실 이것들의 기능이 특정 용도에 제한되어 있지는 않아요.

예를 들어 이 post하나로도 데이터를 쓰고 읽고 수정하고 지우고까지 다 할 수 있죠.
하지만 누구든 각 요청의 의도를 쉽게 파악할 수 있도록 RESTful하게 API를 만들기 위해서는 이들을 목적에 따라 구분해서 사용해야 해요.

먼저 get은 아까 보여드린 것처럼 데이터를 Read, 조회하는데 사용해요.
이런 URI에 get으로 보내는 요청이 있다면
개발자들은 "아, 이 반의 학생들을 보는 요청이구나." 하고 대번에 짐작할 수 있죠.

post는 Create, 새로운 정보를 추가하는데 사용해요.
이 반에 새 학생이 들어와서 정보를 추가하려면 이렇게 URI를 짜고 post요청을 작성해서 body에 새 학생의 정보를 실어보내죠.

학생의 idx는 보통 정보가 추가되면서 생성되기 때문에 post요청에서는 명기할 필요가 없겠죠.

그런데 이 idx를 가진 학생의 정보들이 변경되었어요.
그럴 때는 URI에 변경할 학생의 idx까지 명기한 다음 put또는 patch를 사용해서 변경, Update 될 새 정보들을 역시 body에 실어보내요.

put과 patch의 사용은 쓰는 곳마다 다르고 그냥 put으로 다 하는 곳들도 있는데 알려진 정석은 put은 정보를 통째로 갈아 끼울 때

그리고 patch는 정보 중 일부를 특정 방식으로 변경할 때 사용하는 거에요.

어떤 학생이 학원을 그만두면, Delete를 사용해야겠죠? 당연히 URI는 그 학생의 idx까지 표시해야 할거에요.

말씀드렸다시피 post나 put 같은 것 하나로도, 용량이 적고 중요도가 낮은 정보들은 get으로도 이 4가지가 다 가능하겠지만

이것들로 구분 가능한 요청들을 만들어내려면
이렇게 URI에 이들의 동작까지 명기해야 할 거에요.

정석에 비해 뭔가 깔끔하지가 않죠?

이런 것들을 지양하기 위한 REST의 규칙 중 하나로,
URI는 동사가 아닌 명사들로 이뤄져야 한다는 게 있죠.

결국 REST API란, HTTP 요청을 보낼 때 어떤 URI에 어떤 메소드를 사용할지 (+ 기타) 개발자들 사이에 널리 지켜지는 약속이에요.

이미 말했듯, 형식이기 때문에, 기술에 구애받지는 않죠.

여러분이 앱을 만들든, 웹사이트를 만들든, 그것들을 어떤 언어로 뭘 써서 만들든, 거기에 소프트웨어 간에 HTTP로 정보를 주고받는 부분이 있다면 이 형식, 규칙들을 준수해서 RESTful한 서비스를 만드는 연습을 해보실 수 있을거에요.

오늘 이 방송에서 말씀드릴 것들은 REST API의 아주 기초적인 부분들이고요.
인터넷에
이런 키워드들로 검색해보시면 보다 자세한 내용들을 찾아보실 수 있어요.

용도에 따라 REST API의 대안으로 떠오르는 GraphQL에 대해서도 이후 다뤄보도록 하겠습니다.

영상에 대한 정리와 더불어 gmlwjd9405님의 블로그를 참조하여 개인적으로 정리해보도록 하겠다.

REST란?

REST의 정의는 "Representational State Transfer"이다.
이것은 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다.
구체적으로는, HTTP URI(Uniform Resource Identifier)를 통해 자원(Resourece)를 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.

이 REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍셔 스타일이다.

REST의 장점

HTTP 프로토콜의 인프라를 그대로 사용하기 때문에 REST API 사용을 위해 별도의 인프라를 구축할 필요가 없다.
HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해준다.
HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
서버와 클라이언트의 역할을 명확하게 분리한다.

REST의 단점

표준이 존재하지 않는다.
사용할 수 있는 메소드가 4가지밖에 없다. (HTTP Method 형태가 제한적이다.)
브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 값이 왠지 더 어렵게 느껴진다.
구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 존재한다.
- PUT, DELETE를 사용하지 못하는 점
- pushState를 지원하지 않는 점

REST가 필요한 이유

'애플리케이션 분리 및 통합'
다양한 클라이언트의 등장
최근의 서버 프로그램은 다양한 브라우저와 안드로이드폰, 아이폰과 같은 모바일 디바이스에서도 통신을 할 수 있어야 한다.
이러한 멀티 플랫폼에 대한 지원을 위해 서비스 자원에 대한 아키텍처를 세우고 이용하는 방법을 모색한 결과, REST에 대한 관심을 가지게 되었다.

REST 구성 요소

자원(Resource): URL
- 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
- 자원을 구별하는 ID는 '/groups/:group_id'와 같은 HTTP URI다.
- Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조직을 Server에 요청한다.
행위(Verb) : HTTP Method
- HTTP 프로토콜의 Method를 사용한다.
- HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다.
표현(Representation of Resource)
- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
- Rest에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
- JSON 혹은 XML을 통해 데이터를 주고 받는 것이 일반적이다.

REST API란?

API(Application Programming Interface)란
- 데이터와 기능의 집합을 제공하여 컴퓨터 프로그램간 상호작용을 촉진하며, 서로 정보를 교환가능하도록 하는 것.
REST API의 정의
- REST 기반으로 서비스 API를 구현한 것
- 최근 OpenAPI(누구나 사용할 수 있도록 공개된 API: 구글 맵, 공공 데이터 등), 마이크로 서비스(하나의 큰 애플리케이션을 여러 개의 작은 애플리케이션으로 쪼개어 변경과 조합이 가능하도록 만든 아키텍쳐) 등을 제공하는 업체 대부분은 REST API를 제공한다.

REST API의 특징

사내 시스템들도 REST 기반으로 시스템을 분산해 확장성과 재사용성을 높여 유지보수 및 운용을 편리하게 할 수 있다.
REST는 HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 클라이언트, 서버를 구현할 수 있다.

REST API 설계 기본 규칙

참고 리소스 원형

도큐먼트 : 객체 인스턴스나 데이터베이스 레코드와 유사한 개념

컬렉션 : 서버에서 관리하는 디렉터리라는 리소스

스토어 : 클라이언트에서 관리하는 리소스 저장소

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

resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
resource의 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
resource의 컬렉션 이름으로는 복수 명사를 사용해야 한다.
resource의 스토어 이름으로는 복수 명사를 사용해야 한다.
Ex) GET /member/1 -> GET /members/1

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

URI에 HTTP Method가 들어가면 안된다.
Ex) GET /members/delete/1 -> DELETE /members/1
URI에 행위에 대한 동사 표현이 들어가면 안된다.(즉, CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.)
Ex) GET /members/show/1 -> GET /members/1
Ex) GET /members/insert/2 -> POST /members/2
경로 부분 중 변하는 부분은 유일한 값으로 대체한다.(즉, :id는 하나의 특정 resource를 나타내는 고유값이다.)
Ex) student를 생성하는 route: POST /students
Ex) id=12인 student를 삭제하는 route: DELETE /students/12

REST API 설계 규칙

슬래시 구분자(/ )는 계층 관계를 나타내는데 사용한다.
Ex) http://restapi.example.com/houses/apartments
URI 마지막 문자로 슬래시(/ )를 포함하지 않는다.
- URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.
- REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.
  Ex) http://restapi.example.com/houses/apartments/ (X)
하이픈(- )은 URI 가독성을 높이는데 사용
- 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다.
밑줄(_ )은 URI에 사용하지 않는다.
- 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 하므로 가독성을 위해 밑줄은 사용하지 않는다.
URI 경로에는 소문자가 적합하다.
- URI 경로에 대문자 사용은 피하도록 한다.
- RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문
파일확장자는 URI에 포함하지 않는다.
- REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
- Accept header를 사용한다.
  Ex) http://restapi.example.com/members/soccer/345/photo.jpg (X)
  Ex) GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg (O)
리소스 간에는 연관 관계가 있는 경우
- /리소스명/리소스 ID/관계가 있는 다른 리소스명
  Ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

페리

이전 포스트

프론트엔드 면접 대비

다음 포스트