> RESTful API란?
▶︎ REST란?
REST(REpresentational State Transfer)은 웹에서 자원(resource)이라고 표현되는
이미지, 동영상 등의 데이터에 고유의 URI를 붙여 주소를 지정해주는
규칙과 방법론을 말한다.
💡 URI(통합 자원 식별자, Uniform Resource Identifier)
인터넷에 있는 자원을 나타내는 유일한 주소
지금은 REST와 관련된 정의를 알아보기보다 REST 아키텍쳐가 RESTful API로 이어져
실재로 어떻게 사용되는지 실질적인 측면에서 접근해보려 한다.
때로는 개념에 대한 이해보다 직접적인 사용을 통한 체득 과정을 거치는 것이
그 대상을 이해하는데 시간과 정신적 소모에서 훨씬 효율적이라고 생각한다.
누군가 좋아하는 사람이 생긴다면 너무 그사람에 대해 관찰하고 이해하려고만
하지 말고 일단 말을 붙여보고 상대방을 직접 겪어보는게 나을 때가 많다.
-저녁 11:32분, 밤갬성🌃
▶︎ RESTful API
API 설계규칙 중 가장 널리 사용되는 방식으로 REST의 제약들을 준수하여
API를 작성했을 때 그 시스템을 RESTful하다고 표현한다.
RESTful API는 그 주소만 보고도 어떤 것을 원하는지 바로 알 수 있는 URI을 만들고
그에 해당하는 API를 만드는 것을 의미한다.
한마디로 규칙을 준수한 짱짱 직관적인 URI다.
하지만 완전히 표준화되어 정해진 규칙이 없고 실무에 적용하기 어려운 부분 등으로
회사마다 개인마다 다른 형식으로 REST API를 설계/운영하고 있다고 한다.
> RESTful API 설계
▶︎ URI에 대소문자 구분 사용
https://en.dict.naver.com/#/search?query=resource위 URI는 RFC3986 규칙에서 https://en.dict.naver.com/부분
이후에 오는 경로(path)는 대소문자를 구분한다.
따라서 다음 두 URI는 다른 리소스를 가리키고 있게 된다.
http://www.naver.com/products/Cola
http://www.naver.com/products/cola그리고 다음 세개의 리소스는 같은 리소스를 가리킨다.
http://www.naver.com/products/cola
http://www.NAVER.com/products/cola
http://www.NAVER.COM/products/cola같은 리소스를 가리킨다 해도 대소문자를 섞어 사용하는 것은 혼란을 부를 수
있기 때문에 지양하는 편이 좋지만 의미있는 도메인을 위해 나은 결정이 될수도 있다.
▶︎ 띄어쓰기에는 hyphen(-)을 사용
경로 사이에 띄어쓰기로 인해 공백이 있으면 %20이 공백 대신 쓰이곤 한다.
%20 대신 underscore(_)나 hyphen(-)이 들어갈 수 있는데
일반적으로 underscore는 링크가 걸린 부분에 표시되므로 이것과 중복될 경우
리소스로 쓰인 underscore는 가려질 수 있으니 hyphen을 사용하도록 하자.
▶︎ 확장자 사용 반대와 대응 방법
다음 두개 URI의 확장자는 서로 다르고 따라서 URI도 두개인 비효율적인 상황이 된다.
http://www.naver.com/products/cola.text
http://www.naver.com/products/cola.csv서버에 cola.text와 cola.csv 두개 파일을 하나의 리소스로 가져오려면
REST API에서 http://www.naver.com/products/cola에 대한 대응만 하고
Accept header을 요청이 오면 parsing하여 client가 요청한대로 응답해줄 수 있다.
GET /cola HTTP/1.1
Host: naver.com
Accept: text/csv💡 관련 검색어: http content negotiation
▶︎ URI에 CRUD를 쓰면 안됨
리소스에 대한 행위로써 적절한 CRUD HTTP Method를 선택하여 가독성 높은
REST API를 설계하자.
# URI에 CRUD를 쓰지 말자
GET /delete/products/cola HTTP/1.1
POST /update/products/cola HTTP/1.1
# 적절한 HTTP Method를 사용하자
DELET /products/cola HTTP/1.1
PATCH /products/cola HTTP/1.1▶︎ collection과 document - 복수형, 단수형 구분 사용
콜렉션은 도큐먼트(문서, 정보, element)의 집합이며 양쪽 모두 리소스다.
http://www.naver.com/products/beverage/ciders/2위 예시 URI은 products콜렉션 안에 beverage도큐먼트가 있고
그 안에 ciders라는 콜렉션이 있으며 그 안에 2라는 사이다 종류를 가리키는 리소스다.
ciders와 같은 수준의 콜렉션은 coffees, colas 등이 있겠다.
컬렉션은 복수로, 단일 도큐먼트는 단수로 표현한다.
▶︎ 적절한 응답상태 코드
적절한 상태코드를 사용하여 클라이언트에게 알맞은 정보를 줘야한다.
🥕 응답상태 코드: https://developer.mozilla.org/ko/docs/Web/HTTP/Status
> 참고자료
🥕 mozila-REST: https://developer.mozilla.org/ko/docs/Glossary/REST
🥕 remotty-RESTfull: https://remotty.github.io/blog/2014/01/28/lets-study-rest/
🌈 작은 회고 🤔
만족스러운 느낌이 든다.
REST나 RESTful API에 대한 개념과 실재로 어떻게 적용해야하는지
꽤나 많은 부분을 정리할 수 있는 과정이었다.
몇 번 관련내용을 찾아본적은 있었는데 REST 원칙에 대해 읽다가
도통 뭔소린지 뭘 말하고싶은지 정확히 이해가 안됐었다.
URI를 만드는데 규칙을 통해 합의점을 갖고 만들어야한다 정도?
그리고 그동안 모호함만 가지고 있었다.
하지만 예시를 하나씩 이해하며 보다보니 구체적인 내용들이 정리됐다.
자! 다음은 Path & Query parameter다!!!
