이번 글에서는 RESTful API에 대해서 설명합니다.
해당 내용을 잘 이해하기 위해서는 우선 API가 무엇인지 알아야합니다.
0. API
API는 애플리케이션 프로그래밍 인터페이스의 약자입니다. 각 기업에서는 API를 통해 자사 애플리케이션의 데이터 및 기능을 외부 개발자, 비즈니스 파트너, 사내 부서에 공개합니다. 이를 기반으로 문서화된 단일 인터페이스를 통해 여러 서비스와 제품끼리 서로 통신하고 상호 데이터와 기능을 활용할 수 있습니다. 그렇다면 API는 어떻게 작동할까요?
API의 작동방식
API는 컴퓨터나 애플리케이션의 상호 통신 방식을 설명하는 정의된 규칙의 모음입니다. API는 애플리케이션과 웹 서버의 사이에서 중간 계층의 역할을 합니다. 이 과정에서 시스템 간 데이터 전성을 처리합니다.
API의 작동 방식은 다음과 같습니다.
- 클라이언트 애플리케이션에서 정보를 가져오기 위해
API호출을 시작합니다. 이를 요청(Requset)이라고 부릅니다. 애플리케이션에서 웹 서버로 전달되는 이 요청은API의URI를 사용하여 처리합니다.URI에는 요청동사, 헤더, 경우에 따라서는 요청 본문도 포함됩니다. API는 유효한 요청을 받으면 외부 프로그램이나 웹 서버에 호출됩니다.- 서버에
API가 응답하면서 요청받은 정보를 보냅니다. API가 원래 요청했던 애플리케이션에 데이터를 전송합니다.
데이터 전송은 현재 사용 중인 웹서비스에 따라 달라집니다. 이러한 요청 및 응답 프로세스는 모두 API를 통해 이루어집니다. 사용자 인터페이스는 사람의 사용을 목적으로 만들어진 반면, API는 컴퓨터나 애플리케이션에서 사용하도록 설계됩니다.
API는 기능상 보안을 제공합니다. 두 시스템 사이에서 중개자의 역할을 하면서 기능을 추상화 하기 때문입니다.
API 엔드포인트가 서비스 소비자인 애플리케이션과 그 서비스를 제공하는 인프라를 분리합니다. 일반적으로 API 호출 시 인증 자격 증명이 포함되어 서버에 대한 공격 위험을 줄입니다. 그리고 API 게이트웨이는 액세스를 제한하여 보안 위험을 최소화 합니다. 또한 HTTP 헤더, 쿠키, 쿼리 문자열 매개변수에 의해 한층 더 강력한 데이터 보안이 이루어집니다.
간단히 말해보자면
API에 대해서 예시를 들어서 설명해보겠습니다.
고객이 식당에가면 점원이 주문을 받고 그 주문을 주방에 전달합니다. 그 후 주방에서 음식이 나오면 점원이 음식을 들고 다시 고객에게 전달합니다. 여기서 점원이 API입니다.
URI란?
인터넷 자원을 나타내는 고유 식별자입니다. 인터넷에 있는 자료의 ID라고 생각하면 좋을 것 같습니다.
다른 자료가 똑같은 이름을 가지고 있으면 안되기에URI는 유일합니다.
1. REST
REST(Representational State Transfer)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미합니다.
다시 말해
1. HTTP URI을 통해 자원(Resource)를 명시
2. HTTP Method(POST, GET, PUT, DELETE, PATCH 등)를 통해
3. 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 의미합니다.
CRUD Operation이란
CRUD는 대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능인 Create, Read, Update, Delete를 묶어서 일컫는 말입니다.
2. REST 구성요소
REST는 다음 3가지로 구성 됩니다.
1. 자원 (Resource) : HTTP URI
2. 자원에 대한 행위(Verb) : HTTP Method
3. 표현 (Representations) : HTTP Message Pay Load
3. REST의 특징
REST는 총 여섯가지의 특징을 가집니다.
1) 유니폼 인터페이스
유니폼 인테페이스는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말합니다.
2) 무상태성
REST는 무상태성 성격을 갖습니다. 다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않습니다. 그래서 API 서버는 들어오는 요청만을 단순 처리하면 됩니다. 때문에 서비스의 자유도는 높아집니다. 그리고 서버에서 불필요한 정보를 관리하지 않습니다. 이로인해 구현이 단순해집니다.
3) 캐시 가능
REST의 가장 큰 특징은 HTTP 기존 웹표준을 그대로 사용합니다. 그래서 웹에서 사용하는 기존 인프라를 그대로 활용합니다. 따라서 HTTP가 가진 캐싱 기능이 적용됩니다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.
4) 자체 표현 구조
REST는 REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있다.
5) 클라이언트 - 서버 구조
REST 서버는 API 제공한다. 클라이언트는 사용자 인증이나 세션과 로그인 정보를 직접 관리한다. 각각의 역할이 구분된다. 그래서 클라이언트와 서버 개발 내용이 명확해지고 서로간 의존성이 줄어든다.
6) 계층형 구조
REST 서버는 다중 계층으로 구성될 수 있다. 보안, 로드 밸런싱, 암호화 계층을 추가하면 구조상의 유연성을 둘 수 있다. PROXY, 게이트웨이와 같은 네트워크 기반의 중간매체를 사용할 수 있다.
4. RESTful API
RESTful API 란 REST의 원리를 따르는 API 입니다.
하지만 REST를 사용한다고 모두가 RESTful 하지는 않습니다.
REST API 설계 규칙을 올바르게 지킨 시스템을 RESTful 하다고 말할 수 있습니다.
모든 CRUD 기능을 POST로 처리하는 API 혹은 URI 규칙을 지키지 않은 API는 REST API의 설계 규칙을 올바르게 지키지 못한 시스템은 RESTful 하다고 말할 수 없습니다.
따라서 RESTful API 설계를 위한 가이드를 지키는 건 중요합니다.
특하 아래 두가지는 핵심이 되는 가이드입니다.
첫 째, URI는 정보의 자원을 표현해야 합니다.
둘 째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현합니다.
4-1 REST API 중심 규칙
1) URI는 정보의 자원을 표현 (리소스명은 명사)
GET /members/delete/1위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원 표현에 중점을 둬야 합니다.
delete와 같은 행위에 대한 표현이 들어가서는 안됩니다.
2) 자원에 대한 행위는 HTTP Method로 표현
HTTP Method를 통해 수정해 보면
``
DELETE /members/1으로 수정할 수 있습니다.
회원정보를 가져온다면 GET, 회원 추가 시에는 POST를 사용합니다.
회원 정보를 가져오는 URI
GET /members/show/1 (x)
GET /members/1 (o)회원 추가
GET /members/insert/2 (x) - GET 메서드는 리소스 생성에 맞지 않습니다.
POST /members/2 (o)4-2 URI 설계
1) 슬래시 구분자(/)는 계층 관계를 나타냄
http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 합니다. URI가 다르면 리소스가 다릅니다.
반대로 리소스가 다르면 URI도 다릅니다. REST API는 분명한 URI를 만들어 통신을 해야하므로 혼란을 방지하기 위해 URI경로 마지막에는 슬래시를 사용하지 않습니다.
3) 하이픈(-)은 URI 가독성을 높이는데 사용
URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI 경로를 사용한다면 하이픈을 활용해 가독성을 높일 수 있습니다.
4) 밑줄(_)은 URI에 사용하지 않는다.
글꼴에 따라 다르지만 밑줄을 사용하면 가독성이 낮아집니다. 따라서 밑줄 대신 하이픈을 사용합니다.
5) URI 경로에는 소문자를 사용
URI 경로에 대문자 사용은 피해야 합니다. 왜냐하면 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다.
6) 파일 확장자는 URI에 포함시키지 않는다.
http://restapi.example.com/members/soccer/345/photo.jpg (X)REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않습니다.
따라서 Accept header를 사용합니다.
GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg4-3. 리소스 간 관계 표현 방법
REST 리소스 간 연관 관계는 있을 수도 없을 수도 있다.
만약에 있다면 다음과 같은 표현방법을 사용합니다.
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)만약 관계명이 복잡하면 이를 서브 리소스에 명시적으로 표현합니다. 예를 들어 사용자가 '좋아하는' 디바이스 목록을 표현한다면 다음과 같은 표현방법을 사용합니다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)4-4. 자원을 표현하는 Collection과 Document
Document는 단순히 문서로 이해하거나 객체라고 이해합니다. Collection은 문서들의 집합, 객체들의 집합이라고 이해해봅니다. 이 둘 모두 리소스라고 표현할 수 있습니다. 그래서 URI에 표현됩니다.
http:// restapi.example.com/sports/soccer위 URI는 sports 라는 컬렉션과 soccer 라는 도큐먼트로 표현되고 있습니다.
더 구체적으로 예를 들어보면
http:// restapi.example.com/sports/soccer/players/13sports,players는 컬렉션, soccer,13을 의미하는 도큐먼트로 URI가 이루어집니다. 컬렉션은 복수로 사용하고 있는 점이 중요합니다. 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수, 복수를 지켜주면 좀 더 이해하기 쉽습니다.
5. REST 의 장단점
장점
- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
- 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- 서버와 클라이언트의 역할을 명확하게 분리한다.
단점
- 표준이 자체가 존재하지 않아 정의가 필요하다.
- HTTP Method 형태가 제한적이다.
- 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
- 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)
정리
우선 API란 애플리케이션 프로그래밍 인터페이스로, 데이터 및 기능을 외부에 공개하는 역할을 합니다.
REST는 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 아키텍처 스타일입니다.
HTTP URI를 통해 자원을 명시하고 HTTP Method를 통해 해당 자원에 대한 CRUD Operation을 수행합니다.
RESTful API 설계 규칙을 지키기 위해서는 URI 설계, HTTP Method 활용, 리소스 간 관계 표현 방법을 알고 있어야합니다.
RESTful API는 자원을 명시하고 그 자원에 대한 행위를 HTTP Method로 표현하여 효율적 통신을 가능하게 하는 웹 아키텍처 스타일이라고 할 수 있습니다.
출처
https://www.ibm.com/kr-ko/topics/api
https://khj93.tistory.com/entry/%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-REST-API%EB%9E%80-REST-RESTful%EC%9D%B4%EB%9E%80
https://meetup.nhncloud.com/posts/92
