16-1. API란?16-1-1. API 유형16-1-2. REST와 SOAP16-2. REST API란?16-2-1. REST와 REST API16-2-2. REST API의 구성16-2-3. REST API의 특징16-3. RESTful API란? 16-3-1. RESTful API의 정의16-3-2. RESTful API URL 설계규칙16-3-3. REST API 예제16-3-4. REST API 설계조건 충족의 어려움Reference
16-1. API란?
Rest API를 들어가기 앞서서 API가 무엇인지 알아보자.
API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 컴퓨터나 컴퓨터 프로그램 사이의 연결이다. 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 해주는 인터페이스를 뜻한다. 인터페이스를 빌드하거나 사용하는 방법을 기술하는 문서 혹은 표준을 API 사양이라고 한다. [1]
Interface(인터페이스)?
서로 다른 사물이나 시스템 간에 연결하고 소통할 수 있게 하는 매개체를 의미한다.
여러분이 식당에 있는 상황이라고 가정을 해보자. 메뉴를 선택하고 점원에게 선택한 메뉴를 말하면 점원은 주문 받은 내용을 요리사에게 전달하고 다 만든 요리를 점원에게 준다. 점원은 손님에게 요리를 가져다준다. 이때 점원은 손님에게 주문을 받고, 그 내용을 요리사에게 요청한 뒤 음식을 손님에게 전달해주는 역할을 한다. API는 점원과 같은 역할을 한다. API(점원)는 프로그램(손님)이 명령(주문)을 받으면 프로그램(요리사)과 상호작용하여 명령에 대한 결과(요청된 음식)를 전달한다. 그렇다면 왜 손님이 요리사와 상호작용을 할 수는 없는 것일까? 만약 요리사가 프랑스인이고 점원은 의사소통이 가능하지만 손님과 대화하기는 어렵다. 또 다른 경우는 손님이 질문을 했을 때 요리사가 그에 대한 답변을 할 때 전문 용어를 사용한다면 점원은 이해하지만 손님을 그 뜻을 이해하기 힘들다. 이럴 때 점원은 손님에게 알아듣기 쉽게 전달해줄 수 있는 역할이 된다.
“API는 프로그램들이 서로 상호작용 할 수 있도록 하는 매개체이다.”
16-1-1. API 유형
API는 애플리케이션에서 광범위하게 사용된다. 일반적으로 사용되는 API에는 private, public, partner, composite 네가지 유형이 있다. API 유형은 공개 범위에 따라 유형이 달라진다.
1) Private API(내부, 비공개)
: 조직 내에서 시스템과 데이터를 연결하기 위해 조직 내에서만 사용하기 위한 것이다. 조직 내에서 일하는 개발자가 사용할 수 있도록 백엔드 데이터 및 애플리케이션 기능의 일부를 여는 인터페이스이기도 하다. 조직에서 만든 새로운 애플리케이션이 공개적으로 배포할 수 있지만 외부에서 API에 접근 할 수는 없다.
2) Public API(오픈, 공개)
: 웹 및 모바일 개발자가 쉽게 접근하고 사용할 수 있도록 설계한 인터페이스이다. 모두에게 공개되어 누구나 사용 할 수 있다. 오픈 API를 사용하여 시간을 줄이고 비용을 절감할 수 있다. 공개 API는 일반적으로 보통의 인증 및 권한 부여를 포함한다.
3) Partner API(파트너)
: 비즈니스 파트너 또는 조직 외부에서 허가된 사람에게 제공되는 API이다. 공개적으로 사용할 수 없으며 액세스 할 수 있는 특정 권한이 필요하다. 보통 공개 API 개발자 사이트에 있지만 파트너 API는 오픈 API와 달리 완전히 오픈되어 있지 않고 특정 액세스 설정을 해야한다.
4) Composite API(복합)
: 두 개 이상의 API를 결합하여 사용하는 것이다. 복합 API는 복잡하거나 밀접하게 관련된 API 동작을 처리하는 데 도움이 될 수 있으며, 때로는 개별 API보다 속도와 성능을 향상 시킬 수 있다.
16-1-2. REST와 SOAP
브라우저는 HTTP를 통해서 서버와 통신을 주고 받는다. HTTP 프로토콜을 통해서 서버에서 제공하는 웹 API를 이용해 서버의 데이터를 읽고 저장 및 수정이 가능하다. 이러한 HTTP 프로토콜을 통해 웹 애플리케이션 간 데이터 통신을 허용하는 API를 구축하는 방법을 정의하는데 REST와 SOAP가 있다. SOAP는 프로토콜이지만, REST는 프로토콜이 아니고 아키텍처의 한 형식이다. REST는 유연한 구현을 제공하고 SOAP는 XML을 사용하며 특정 요건이 있는 프로토콜이다.
HTTP?
Hypertext Transfer Protocol 약자로 서버가 어떻게 통신하는지를 정해놓은 통신규약이다. 클라이언트가 서버에게 정보를 요청하고 다시 서버에서 정보를 받아오는 request(요청) ↔️ response(응답) 방식이다.
- REST와 SOAP의 다른 점을 표로 비교해보자.
- SOAP는 XML을 데이터 포맷으로 사용한다. XML 샘플 코드로 형식을 확인을 해보자.[2]
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <getProductDetails xmlns="http://warehouse.example.com/ws"> <productId>827635</productId> </getProductDetails> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
16-2. REST API란?
16-2-1. REST와 REST API
REST는 효율적이고 안정적이게 확장 가능한
분산 하이퍼미디어 시스템(ex.웹)의 아키텍처 디자인 제약의 모음을 나타낸다. 다시 말해, REST는 HTTP 프로토콜을 바탕으로 네트워크를 통해 클라이언트가 리소스가 포함된 서버에 접근하는 방식을 나타낸 아키텍처라고 할 수 있다. 이러한 REST 원칙을 준수할 때 ‘RESTful’이라고 한다. [3]
위에 설명한 REST를 통해 REST API는 REST 아키텍처의 제약 조건을 준수하여 API 서비스를 구현한 것임을 쉽게 알 수 있다.16-2-2. REST API의 구성
REST API 의 구성은 자원, 행위, 표현으로 구성된다. 자세한 구성요소의 내용은 다음과 같다.
- 자원 (Resource) 리소스는 REST의 기본 개념으로 표준화된 작동방식을 가지고 전송되는 문서라고 할 수 있으며 이름을 붙일 수 있는 모든 정보는 자원이 될 수 있다. 리소스를 표현하는 방법으로는 URI가 있다.
- 행위 (Verb) HTTP 프로토콜의 메소드를 사용하며 해당 메소드는 CRUD를 가능하게 한다. HTTP 프로토콜 메소드의 구성은 POST, GET, PUT, DELETE 이다.
- 표현(Representations) 클라이언트가 리소스의 조작을 요청하면 해당 자원에 대한 서버의 행위, 즉 서버의 응답을 보낸 것으로 주로 JSON을 통해 데이터를 주고 받는다.
16-2-3. REST API의 특징
REST API는 XML-RPC, SOAP등의 일부 API보다 사용하기 용이하다. REST API는 HTTP 프로토콜 기반으로 다양한 포맷의 데이터 지원이 가능하고 HTTP를 지원하는 프로그래밍 언어를 이용해 개발할 수 있다. 특히 프로그래밍 언어 중 JSON의 사용 비중이 높다. JSON은 여러 프로그래밍 언어로 읽을 수 있고, 경량화 되어 있기 때문에 REST API를 유연하게 설정하기 용이하다.[4]
이처럼 REST API는 빠른 속도와 경량화로 사물인터넷, 모바일 앱 개발, 서버리스 컴퓨팅 등에 적합하다.[5]
16-3. RESTful API란?
개발자 채용공고를 보다보면, 자격요건에서 RESTful API 라는 말을 자주 볼 수 있다. 이것은 프론트엔드 개발자, 백엔드 개발자 모두에게 중요한 것으로 생각하면 될 것이다. 그렇다면 이전까지 본 REST API와 무슨 차이가 있을까?
16-3-1. RESTful API의 정의
위에서 설명한 REST 설계 규칙을 지킨 API를 RESTful API 라고 한다. 내가 짠 코드를 다른 사람들이 쉽게 이해하도록 코딩 컨벤션이 존재하듯이 REST API의 각 요청이 어떤 동작이나 정보를 위한 것인지 쉽게 파악 하도록 하는 것을 목적으로 한다.
16-3-2. RESTful API URL 설계규칙
- URL에 CRUD를 사용하면 안된다.
- 공백, ‘ _ ‘을 제거해야하고 대신 hypen(-) 을 사용해야한다.
- 대소문자를 구분하기때문에, 소문자가 적합하다.
- header에 값을 넣고, 확장자 사용을 지양해야한다.
16-3-3. REST API 예제
다시 한번 정리하자면, REST API 설계 시 URI로 정보의 자원을 표현하고 행위를 HTTP Method인 GET, POST, PUT, DELETE 로 표현해야한다.
다음 예제에서 REST API 규칙을 지켰는지 고민해보고 아래에서 답을 확인해보자.
DELETE /jsmember/delete/1
- 정답 : X
- CRUD 중 DELETE 예제로, 방금 URI같은 경우 REST 원칙이 제대로 지켜지지 않았다. delete와 같은 행위에 대한 표현이 들어가면 안되기 때문이다.
GET /jsmember/2
- 정답 : O
- jsmember 중 2번째인 회원정보를 가져오는 것으로 올바른 Method인 GET을 사용했다.
http://restapi.jsexample.com/member/explain/
- 정답 : X
- URI 마지막 문자는 슬래시를 포함하지 않는다. URI에 포함되는 모든 글자는 resource의 유일한 식별자로 사용되야한다. 따라서, 분명한 URI를 위해, 경로의 마지막에는
/를 사용하지 않는다.
16-3-4. REST API 설계조건 충족의 어려움
제약조건을 따르는 것을 REST라고 한다. 하지만 대부분의 REST API라고 하는 것들은 REST를 지키지 못하고 있는 경우가 많다. REST 지침을 만든 Roy Fielding 박사는 심지어 Microsoft가 2016년 발표한 REST API 가이드라인조차 REST API가 아니라고 부정했을정도니 얼마나 어려운지 체감될 것이다.