REST API

REST API라는 말을 많이 들어보셨을 겁니다. 얼핏 보고 구현한 다음 RESTful 하다고 하는 경우가 많습니다. 물론 저도 그랬습니다. RESTful하게 만들기 위해 공부를 더했고, 그 과정에서 배운 것을 합쳐 REST API에 대해 알아보겠습니다.
먼저 API란 Application Programming Interface의 약자 입니다. API는 응용 프로그램이 서로 통신할 수 있도록하는 일련의 규칙입니다. 개발자는 서버에서 API를 만들어 클라이언트와 대화할 수 있습니다.

REST는 Representational State Transfer의 약자로 분산 네트워크 프로그래밍의 아키텍처 스타일입니다. REST는 API의 구조(모양) 중 하나라고 생각하면 됩니다. 방식은 간단합니다. 예를 들어 네이버 검색창에 무엇인가를 검색하면 결과가 출력됩니다. 이 처럼 검색창에 입력하여 전송하는 것이 request, 검색된 결과를 서버에서 보내주는 것이 response 입니다. 가장 기초적인 것부터 알아보도록 하겠습니다.

Request

request는 4가지로 구성되는데 이는 상당히 중요합니다.

The endpoint
The method
The headers
The data(or body)

엔드 포인트(The endpoint)

엔드 포인트는 요청한 url입니다.

root-endpoint/?

root-endpoint는 클라이언트가 요청한 API의 시작점 입니다. 네이버 API의 경우 https://openapi.naver.com이 root-endpoint 입니다. 뒤의 ’?’는 path입니다. path는 요청한 리소스를 결정해 줍니다. 예를 들어 1번 버튼을 누르면 서비스1이 실행되고 2번 버튼을 누르면 서비스2가 실행되는 느낌입니다. path를 붙이면 https://openapi.naver.com/v1/search/blog와 같습니다. 이는 블로그 검색을 호출한다는 의미 입니다. 사용가능한 path에 대해서는 API 문서를 확인해 봐야 합니다.
path에 값(변수)를 대입하거나 query string(parameter)를 이용하는 경우도 있습니다.

/user/:username/friend

만약 위와 같은 path가 있다면 :username에 결과를 원하는 사용자 이름을 대입하여 요청을 보내야 합니다.
query string은 사용법이 정말 많은 경우도 있습니다. query string은 기본적으로 ?로 시작하여 &로 구분하여 parameter를 이어 갑니다.

/v1/search/book.xml?query=%EC%A3%BC%EC%8B%9D&display=10&start=1

위의 query string을 보게 되면 3개의 parameter가 있습니다. query는 검색하고자하는 문자열, display는 검색 결과 갯수 지정, start는 검색위치로 부터 갯수입니다. 이렇게 query string을 지정하여 더욱 상세한 조회가 가능합니다.

Method

메소드는 총 5개가 존재합니다.

GET
POST
PUT
PATCH
DELETE 그러나 PATCH를 제외하고 4개를 사용합니다. 이 4개의 메소드는 CRUD(Create, Read, Update, Delete)의 기능을 수행합니다. 이 메소드들의 사용에 대해 알아보겠습니다.

Method	Meaning
GET	Get 메소드는 서버로부터 정보를 가져올 때 사용이 됩니다.(Read)
POST	리소스를 생성할 때 사용이 됩니다.(Create)
PUT	리소스를 수정(update) 할 때 사용이 됩니다.(Update)
DELETE	리소스를 제거할 때 사용이 됩니다.(Delete)

이름과 의미가 일치? 하는 부분이 어느 정도 있어서 외우기 쉬운편 입니다. 한 가지 알아둬야 할 것은 GET은 기본적으로 요청에 대해서 같은 응답임을 보장합니다. 그러나 POST의 경우에는 같은 응답을 보장하지 않습니다. 때문에 브라우저에서 GET방식으로 요청을 하고 난 뒤에 뒤로가기를 해도 아무런 변화가 없지만, POST일 때 뒤로가기를 클릭하면 ‘양식 다시 제출 확인’이란 문구가 모든 브라우저에서 공통적으로 나타납니다.

Headers

Header는 서버와 클라이언트 모두에게 정보를 제공해 줍니다. 다양한 정보가 담겨 있고, 다양한 목적으로 사용이 됩니다. 예를 들어 body에 담겨 있는 Content-Type이나 인증 정보 Authorization 등이 담겨 있습니다.
또한 클라이언트에서 헤더 정보를 먼저 읽을 수 있으므로 본문 내용을 읽을 필요가 없어 통신 효율이 좋습니다.

Data

Data는 body나 message로 불리기도 합니다. 서버에 요청하기 위한 데이터가 담겨 있습니다. Get 메소드의 경우에는 body가 없지만 POST의 경우에는 요청이 body가 되므로 URL을 직접 호출할 수 없습니다.

지금까지 기본적인 Request에 대해 알아봤습니다. 이제 본격적으로 REST에 대해 알아보겠습니다.

REST

REST의 특징

클라이언트/서버 : 클라이언트와 서버가 서로 독립적이어야 하고, 서로 의존성 때문에 확장에 문제 되는 일이 없어야 한다.
상태 없음 : 서버는 클라이언트의 상태를 기억할 필요가 없다.
레이어드 아키텍처(Layered Architecture) : 서버와 클라이언트 사이에 다계층 형태로 레이어를 추가,수정, 삭제 등 확장성이 있어야 한다.
캐시(cache) : 캐시를 가지고 있을 경우 클라이언트가 이를 통해 응답을 재사용하여 서버의 부하를 낮출 수 있다.
코드 온 디멘드(code on demand) : 요청이 오면 코드를 준다는 말 그대로 클라이언트에서 서버를 동작시켜 원하는 기능을 수행하도록 하는 것이다.
통합 인터페이스 : 서버와 클라이언트간의 상호 작용은 일관된 인터페이스들 위에서 이뤄줘야 한다.

REST 인터페이스 규칙

통합 인터페이스를 위한 4가지 규칙

리소스 식별 : URI와 같은 고유 식별자를 통해 서보 구분할 수 있다.
표현을 통한 리소스 처리 : JSON, XML, HTML과 다양한 콘텐츠가 있어도 데이터는 변경되지 않는다.
자기 묘사 메세지 : HTTP Header에 데이터에 대한 설명을 나타내는 정보를 담을 수 있다.
애플리케이션의 상태에 대한 하이퍼미디어 : 단순 데이터만 전달하지 않고, 링크 정보까지 포함하면 웹에 좀더 친숙한 API가 될 수 있다.

위의 사항들을 준수한 경우 RESTful하다고 하며 RESTful한 API를 REST API라고 한다. 그러나 반드시 REST한 특성을 모두 준수할 필요는 없다.(준수하기 어려워서 이기도 하다.)

여기 RESTful에 대한 좋은 글이 있다.

13 Best Practices(RESTful API Design)(https://florimond.dev/blog/articles/2018/08/restful-api-design-13-best-practices-to-make-your-users-happy/)

이 글에서 작성자가 직접 여러 API를 사용해보고 만들어 보며 느낀 RESTful에 대한 권장사항을 말하고 있습니다. 한번 읽어보면 큰 도움이 될 것 입니다. REST API에 대한 실습은 추후에 진행하도록 하겠습니다. 감사합니다!

참고

MDN HTTP header(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)
Understanding REST APIs(https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/)
스프링부트로 배우는 자바 웹 개발(저자 : 윤석진)

[SpringBoot] REST API란?

REST API in Spring boot