REST API, 라이브러리 vs API vs 프레임워크 vs 컴포넌트 vs 모듈 vs 패키지

 

REST API(Representational State Transfer Application Programming Interface)

 - 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다.

 

• 구성
  • 자원(Resource) - URI
  • 행위(Verb) - HTTP METHOD
  • 표현(Representations) : JSON, XML ,TEXT, RSS 등의 표현이 존재한다.
• 특징
  1. Uniform(유니폼 인터페이스) : URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일.
  2. Stateless(무상태성) : REST는 무상태성 성격을 갖는다. 즉, 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
  3. Cacheable(캐시 가능) : HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하다. 따라서 HTTP가 가진 캐싱 기능 적용 가능하다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.
     •  
  4. Self-descriptiveness(자체 표현 구조) : REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어있다.
  5. Client - Server 구조 : REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클과 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어든다.
  6. 계층형 구조 : REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.
• REST API 설계 가이드
  1. 첫 번째, URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다 명사를 사용)
     • GET /members/delete/1
     • 위와 같은 방식은 REST를 제대로 적용하지 않은 URI이다.
     • URI는 자원을 표현하는데 중점을 둬야한다. delete와 같은 행위에 대한 표현이 들어가선 안된다.
  2. 두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
     • DELETE /members/1

위와 같이 URI는 자원을 표현하는 데에 집중하고, 행위에 대한 정의는 HTTP METHOD를 통해 하는 것이 REST API를 설계하는 중심 규칙이다.

 

• URI 설계 시 주의할 점
  1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
     • http://restapi.example.com/animals/mammals/whales
  2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
     • URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며, URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.
     • REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 /를 사용하지 않는다.
  3. 하이픈(-)은 URI 가독성을 높이는데 사용
  4. 밑줄(_)은 URI에 사용하지 않는다.
     • 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 한다. 밑줄 대신 -를 사용하는게 좋다.
  5. URI 경로에는 소문자가 적합하다.
     • 대소문자에 따라 다른 리소스로 인식된다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다.
  6. 파일확장자는 URI에 포함시키지 않는다.
     • REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
     • Accept header를 사용하자.
     • GET /members/soccer/345/photo HTTP/1.1
     • Host : restapi.example.com
     • Accept : image/jpg
• 리소스 간의 관계를 표현하는 방법
  • REST 리소스 간에는 연관 관계가 있을 수 있고, 다음과 같은 표현방법으로 사용된다.
  • /리소스명/리소스ID/관계가 있는 다른 리소스명
  • GET/users/{userid}/devices (일반적으로 소유 'has'의 관계를 표현할 때)
• 자원을 표현하는 Collection과 Document
  • DOCUMENT는 단순히 문서로 이해해도 되고, 한 객체라고 이해해도 된다.
  • COLLECTION은 문서들의 집합, 객체들의 집합.
  • 모두 리소스이며 URI에 표현된다.
  • http://restapi.example.com/sports/soccer
  • sports라는 컬렉션, soccer라는 도큐먼트로 표현되는 중
  • http://restapi.example.com/sports/soccer/players/13
  • sports, players 컬렉션과 soccer, 13를 의미하는 도큐먼트로 URI가 이루어짐.
  • 컬렉션은 복수로 사용하고 있다.
  • 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지킨다면 좀 더 이해하기 쉬운 URI를 설계할 수 있다.
• HTTP 응답 상태 코드
  • 잘 설계된 REST API는 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다.
  • 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수 있다.
  • 200 : 클의 요청을 정상적으로 수행함
  • 201 : 클이 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)
  •  
  • 400 : 클의 요청이 부적절할 경우 사용
  • 401 : 클이 인증되지 않은 상태에서 보호된 리소스를 요청했을 때. (미 로그인 유저가 로그인 했을 때 요청 가능한 리소스를 요청했을 때)
  • 403 : 유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클이 요청했을 때 사용함 (403보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기에)
  • 405 : 클이 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우
  •  
  • 301 : 클이 요청한 리소스에 대한 URI가 변경 되었을 때 (응답 시 Location header에 변경된 URI를 적어 줘야 한다.)
  • 500 : 서버에 문제가 있을 경우 사용함.

 

API란?

• 소프트웨어 간의 응답과 요청을 통한 데이터 통신을 위한 방법과 규칙. API는 OS에서도 제공 (Windows API)할 수 있고, 프로그래밍 언어(Java API)에서도 제공할 수 있고, 웹 어플리케이션(Facebook API)에서도 제공할 수 있다.
• 웹에서는 주로 웹 애플리케이션에서 제공하는 API를 주로 의미한다.
• API는 주로 서버와 클라이언트 관점에서 설명된다. 클은 요청을 보내고, 서버는 요청에 응답한다. 웹 API는 SOAP API, RPC API, Websocket API, REST API 등이 있다.
• 소프트웨어나 시스템 간에 서로 상호작용할 수 있게 해주는 중간 매체이다.
• 함수나 명령어 집합을 제공하며, 한 프로그램이 다른 프로그램의 기능이나 데이터를 사용할 수 있게 해준다.
• 개발자는 복잡한 기능을 직접 구현하지 않고도, 다른 애플리케이션의 기능을 활용해 더 풍부하고 강력한 개발 가능
• 주요 구성 요소
  • 함수 및 메서드 : 개발자가 특정 작업을 수행할 수 있게 해주는 코드 조각. ex)날씨 정보 제공하는 API는 특정 지역의 날씨를 조회하는 함수 제공
  • 데이터 포맷 : json, xml
  • 엔드포인트 : 네트워크 상에서 API가 호스팅되는 특정 URL. 클라이언트는 이 엔드포인트에 요청을 보내고, 응답을 받는다.
  • 문서화 : API의 기능, 사용방법, 엔드포인트 등이 기록된 문서.
• API는 응용 프로그램에서 어떤 프로그램 혹은 기능을 사용할 수 있도록 지켜야할 규칙들을 모아놓은 것이다.
  • ~~, ~~이러한 형식을 제공할 테니 기능 사용할 수 있도록 해주세요. (형식 = API)
  • 넵. 규칙이 맞으니 응답 드리겠습니다.
• API 를 정의하고, 그 규칙에 따라 API에서 기능을 부르면 그 기능을 사용할 수 있다.
• 보안성 강화: API 를 사용하면, 그 안에 코드를 몰라도 그 기능을 쓸 수 있으므로
• 커뮤니케이션 증진: 서버가 어떤 기능을 가지고 있고 어떻게 요청해야하는지 클라이언트가 API를 통해 알 수 있다.

REST API란?

• REST 아키텍처의 제약 조건을 준수하는 API.
• REST 제약 조건을 잘 준수함을 RESTful하다고 표현.
• REST는 일반적으로 통용되는 규약이다. 즉 정답이 아니라 일반적으로 권고되는 규칙이다.
• STATELESS하게 동작한다.
• REST API에서는 주로 토큰 기반 인증 방식을 사용한다. OAuth, JWT같은 토큰 기반 시스템은 사용자가 로그인을 하면, 서버가 토큰을 발급하고, 클은 이후의 요청에 이 토큰을 포함시켜 서버에 전송한다. 서버는 토큰을 검증하여 요청을 처리한다.

 

 

라이브러리 vs API vs 프레임워크 vs 컴포넌트 vs 모듈 vs 패키지

라이브러리

• 재사용 가능한 코드의 집합으로, 특정 기능을 구현한 클래스나 함수들을 모아 놓은 것.
• 개발자가 직접 코드의 흐름을 제어하며 필요한 부분에서 호출하여 사용한다.
• ex) java.util 라이브러리는 날짜, 시간 처리, 자료 구조 등 다양한 유틸리티 기능 제공

API

• 소프트웨어 간 상호작용을 위한 명세이다. 프로그램이 서로 통신할 수 있도록 해주는 함수, 메서드, 프로토콜, 도구의 집합을 말한다. 
• 트위터 API를 사용하면 개발자가 트위터의 기능을 자신의 애플리케이션 내에서 사용할 수 있다.

프레임워크

• 애플리케이션의 기본 흐름과 구조를 제어한다. 개발자는 프레임워크가 정한 규칙과 구조 내에서 코드를 작성한다.
• IoC(제어의 역전) 개념과 관련이 깊다.

컴포넌트

• 재사용 가능한 소프트웨어 객체로, 특정 기능을 수행하는 독립적인 단위.
• 일반적으로 잘 정의된 인터페이스를 가지고 있으며, 이를 통해 애플리케이션의 다른 부분과 상호작용한다.
• GUI 요소(버튼, 텍스트 박스)부터, 더 큰 범위의 서비스(웹 검색 서비스)까지 다양하다. 
• 컴포넌트는 런타임 엔티티를 참조하는 단위

모듈

• 관련된 기능들을 묶어서 독립적으로 분리한 코드 단위이다. 모듈 내의 함수나 클래스는 모듈 밖에서도 사용될 수 있으며, 이를 통해 코드의 재사용성과 유지보수성이 향상된다. 
• 프로그램의 다른 부분과 명확히 구분되며, 종종 개별적으로 컴파일될 수 있다. ex. 파이썬 import로 모듈 불러오기.
• 모듈은 가장 상위에 위치하는 구현의 단위,

1개의 서버에게 서비스를 제공받는 100개의 클라이언트가 존재한다고 가정하자.

위에 설명한 내용으로 모듈, 컴포넌트의 개수를 각각 세어보면

서버가 구현된 모듈 1개, 클라이언트가 구현된 모듈 1개이므로

이 시스템 인프라의 총 모듈 개수는 2개이다.

컴포넌트의 경우 실제 동작하고 있는 엔티티를 의미하므로 총 101개가 된다.

 

 

 

참고 문헌 : https://inpa.tistory.com/entry/WEB-%F0%9F%8C%90-REST-API-%EC%A0%95%EB%A6%AC