REST API는 HTTP 지식과 관련이 있습니다. HTTP과 관련한 글은 이 편에서는 간략하게 다루고, 오늘은 'REST API 위주'로 글을 쓰도록 하겠습니다. HTTP 관련 글은 추후에 업로드 할 예정입니다.

우선 API에 대해서 살펴보겠습니다.

1. API란?

  • 애플리케이션 프로그래밍 인터페이스(Application Programming Interfaces, API) 는 애플리케이션 소프트웨어 및 서비스를 통합하는 툴, 정의, 프로토콜의 세트입니다. 이는 새로운 연결 인프라를 지속적으로 구축할 필요 없이 제품 및 서비스가 서로 커뮤니케이션할 수 있도록 도와주는 기능입니다.
  • API는 전용으로 지정하거나(내부용), 파트너용(특정 파트너와 공유하여 추가 수익원 제공), 또는 공용(타사가 혁신을 촉진하기 위해 API와 통신하는 애플리케이션을 개발하도록 지원)으로 사용할 수 있습니다.
  • API를 사용하면 구현 방식을 알지 못해도 제품 또는 서비스가 서로 커뮤니케이션할 수 있으며 애플리케이션 개발을 간소화하여 시간과 비용을 절약할 수 있습니다. 새로운 툴과 제품을 설계하거나 기존 툴과 제품을 관리하는 경우 API는 유연성을 제공하고 설계, 관리, 사용 방법을 간소화하며 혁신의 기회를 제공합니다.
  • API는 당사자들 간 계약을 나타내는 도큐멘테이션을 갖춘 계약으로 비유되기도 합니다. 한쪽 당사자가 특정한 방식으로 구성된 원격 요청을 보내면 다른 쪽 당사자의 소프트웨어가 이에 응답하는 방식이기 때문입니다.
  • API는 개발자가 새로운 애플리케이션 구성 요소를 기존 아키텍처에 통합하는 방식을 간소화하므로 비즈니스 팀과 IT팀 간의 협업에도 도움이 됩니다. 디지털 시장은 새로운 경쟁 기업이 새로운 애플리케이션과 함께 등장하여 업계 전체의 판도를 바꾸기도 하는 등 끊임없이 변화할 수밖에 없으므로, 이에 대응해 비즈니스 요구사항도 빠르게 변화하는 경우가 많습니다. 따라서 경쟁력을 유지하려면 혁신적인 서비스를 신속하게 개발하고 배포하도록 지원해야 합니다. 클라우드 네이티브 애플리케이션 개발은 개발 속도를 높이기 위한 식별 가능한 방식이며, API를 통한 마이크로서비스 애플리케이션 아키텍처 연결에 기반합니다.

2. REST API의 탄생

  • REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었습니다.
  • 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했습니다.

REST: 웹의 장점을 최대한 활용할 수 있는 아키텍쳐

3. REST 구성

쉽게 말해 REST API는 다음의 구성으로 이루어져있습니다. 자세한 내용은 밑에서 설명하도록 하겠습니다.

자원(RESOURCE) - URI
행위(Verb) - HTTP METHOD
표현(Representations)

4. REST 의 특징

1) Uniform (유니폼 인터페이스)

  • Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말합니다.

2) Stateless (무상태성)

  • REST는 무상태성 성격을 갖습니다. 다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다.

3) Cacheable (캐시 가능)

  • REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능합니다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능합니다.

내가 몰라서 찾아본 것 - 캐시란?

  • 캐싱 기본 개념 : 캐싱(Caching)은 애플리케이션의 처리 속도를 높여줍니다. 이미 가져온 데이터나 계산된 결과값의 복사본을 저장함으로써 처리 속도를 향상시키며, 이를 통해 향후 요청을 더 빠르게 처리할 수 있다. 대부분의 프로그램이 동일한 데이터나 명령어에 반복해서 엑세스하기 때문에 캐싱은 효율적인 아키텍처 패턴이다.
  • 웹 캐시(WEB Cache) : 사용자(client)가 웹 사이트(server)에 접속할 때, 정적 컨텐츠(이미지, JS, CSS 등)를 특정 위치(client, network 등)에 저장하여, 웹 사이트 서버에 해당 컨텐츠를 매번 요청하여 받는것이 아니라, 특정 위치에서 불러옴으로써 사이트 응답시간을 줄이고, 서버 트래픽 감소 효과를 볼 수 있다.

4) Self-descriptiveness (자체 표현 구조)

  • REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것입니다.

5) Client - Server 구조

  • REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 됩니다.

6) 계층형 구조

  • REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.

위의 6 가지의 조건을 잘 지키는 것을 보고, RESTful 하다고 합니다.

5. REST API 디자인 가이드

  1. URI는 정보의 자원을 표현해야 합니다.
  2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현합니다.

5-1. REST API 중심 규칙

  1. URI는 정보의 자원을 표현해야 합니다. (명사 사용)

    GET/members/post/1

위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원을 표현하는데 중점을 두어야 합니다. post와 같은 행위에 대한 표현이 들어가서는 안됩니다.

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

위의 잘못 된 URI를 HTTP Method를 통해 수정해 보면

POST/members/1

으로 수정할 수 있겠습니다.
회원정보를 가져올 때는 GET, 회원 추가 시의 행위를 표현하고자 할 때는 POST METHOD를 사용하여 표현합니다.

회원정보를 가져오는 URI

GET /members/show/1 (x)
GET /members/1 (o)

회원을 추가할 때

GET /members/insert/2 (x) - GET 메서드는 리소스 생성에 맞지 않습니다.
POST /members/2 (o)

5-2. URI 설계 시 주의할 점

1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

3) 하이픈(-)은 URI 가독성을 높이는데 사용

4) 밑줄(_)은 URI에 사용하지 않는다.

5) URI 경로에는 소문자가 적합하다.

6) 파일 확장자는 URI에 포함시키지 않는다.

  • REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않습니다. Accept header를 사용하도록 합시다.

5-3. 리소스 간의 관계를 표현하는 방법

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용합니다.

/리소스명/리소스 ID/관계가 있는 다른 리소스명

만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.

GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

5-4. 자원을 표현하는 Colllection과 Document

  • Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워집니다. DOCUMENT는 단순히 문서로 이해해도 되고, 한 객체라고 이해하셔도 될 것 같습니다. 컬렉션은 문서들의 집합, 객체들의 집합이라고 생각하시면 이해하시는데 좀더 편하실 것 같습니다. 컬렉션과 도큐먼트는 모두 리소스라고 표현할 수 있으며 URI에 표현됩니다. 예를 살펴보도록 하겠습니다.

http:// restapi.example.com/sports/soccer

위 URI를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있다고 생각하면 됩니다. 좀 더 예를 들어보자면

http:// restapi.example.com/sports/soccer/players/13

  • sports, players 컬렉션과 soccer, 13(13번인 선수)를 의미하는 도큐먼트로 URI가 이루어지게 됩니다. 여기서 중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다. 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.



출처
https://hahahoho5915.tistory.com/33
https://meetup.toast.com/posts/92
profile
<'쟤'보단 내가 낫지> 에서 '쟤'를 담당하고 있습니다.

0개의 댓글