API (Application Programming Interface)

프로그램끼리 서로 통신할 수 있도록 하는 인터페이스를 말합니다. 간단하게 설명하면, 소프트웨어의 기능을 다른 소프트웨어나 애플리케이션에서 사용할 수 있도록 제공하는 방법이라고 할 수 있습니다.

API는 크게 두 가지 종류로 나뉩니다.

외부 API (External API):

• 외부 API는 다른 기업이나 개발자가 제공하는 인터페이스입니다.
• 예를 들어, 지도 서비스의 API를 사용하여 위치 정보를 가져오거나, 결제 서비스의 API를 사용하여 결제를 처리할 수 있습니다.
• 대표 프로토콜: http

내부 API (Internal API 또는 Private API)

• 내부 API는 같은 조직 내에서 서로 다른 시스템이나 서비스 간에 통신할 수 있도록 하는 인터페이스입니다.
• 예를 들어, 회사의 데이터베이스 시스템과 웹 애플리케이션 간에 데이터를 주고받을 때 내부 API를 사용할 수 있습니다.
• 대표 프로토콜: gRPC, MySQL Protocol

웹 API

웹 API는 http 프로토콜를 사용하는 API 입니다. 웹 서버와 클라이언트(웹 브라우저, 모바일 앱 등) 사이의 상호작용을 위해 정의된 인터페이스입니다. 이러한 API를 통해 클라이언트는 서버로부터 데이터를 요청하거나 서버에 데이터를 전송할 수 있습니다.

웹 API는 다음과 같은 특징을 가집니다:

• HTTP 기반: 웹 API는 HTTP 프로토콜을 사용하여 데이터를 송수신합니다. 이는 웹 API가 플랫폼 독립적이며 다양한 클라이언트에서 사용할 수 있음을 의미합니다.
• 데이터 포맷: 일반적으로 JSON 또는 XML 형식을 사용하여 데이터를 교환합니다. 이 포맷들은 웹에서 데이터를 쉽게 처리하고 파싱할 수 있게 해줍니다.
• 상태 비저장: API는 상태를 유지하지 않습니다. 즉, 각 요청은 독립적이어야 하며, 요청 간에 클라이언트의 상태 정보를 서버가 기억해서는 안 됩니다.

REST(Representational State Transfer)

웹 API를 설계할때 다양한 아키텍쳐 스타일(SOAP, GraphQL, REST) 사용할 수 있습니다. 이 중 REST API는 REST 아키텍처 스타일의 디자인 원칙을 준수하는 API입니다. 이러한 이유로 REST API를 RESTful API라고도 합니다.

REST는 2000년에 로이 필딩(Roy Fielding)의 박사 학위 논문에서 처음 소개되었습니다. 이 아키텍처는 네트워크 상의 자원을 효과적으로 정의하고 주소를 할당하여 쉽게 접근하고 사용할 수 있도록 설계된 원칙과 제약 조건의 집합입니다.

REST의 핵심 원칙

REST 아키텍처는 다음과 같은 주요 원칙을 기반으로 합니다:

1. 자원(Resource)의 식별: 웹 상의 모든 자원(문서, 이미지, 데이터)은 각각 고유한 URI(Uniform Resource Identifier)를 통해 식별되어야 합니다.

2. 자원에 대한 표현: 클라이언트가 서버로부터 자원의 상태(리소스 표현)를 요청할 때, 서버는 JSON, XML, HTML 등의 형태로 자원의 상태 정보를 클라이언트에게 전달합니다.

3. 자기 기술적 메시지(Self-descriptive messages): 요청 메시지는 어떻게 처리해야 할지 충분한 정보를 포함해야 하며, 응답 메시지는 요청을 어떻게 처리했는지 충분한 정보를 포함해야 합니다.

4. 상태 없음(Stateless): 각 요청은 독립적이며 서버는 클라이언트의 상태 정보를 저장하거나 관리하지 않습니다. 모든 필요한 정보는 각 요청에 포함되어야 합니다.

5. 계층화 시스템(Layered System): 클라이언트는 중간 서버를 거쳐 최종 서버에 접근할 수 있으며, 중간 서버는 로드 밸런싱이나 캐시 등의 기능을 제공할 수 있습니다.

6. 코드 온 디맨드(Code on demand) (선택적): 서버는 실행 가능한 코드를 클라이언트에 전송할 수 있어, 클라이언트의 기능을 일시적으로 확장할 수 있습니다. 이 원칙은 선택적으로 사용됩니다.

REST 핵심 요소

REST API는 다음의 핵심 요소로 이루어져있습니다.

자원 (Resources)

REST 아키텍처에서 자원은 웹 기반 시스템에서 관리되는 모든 항목을 의미합니다. 자원은 보통 명사로 표현되며, 각 자원은 고유한 URI(Uniform Resource Identifier)에 의해 식별됩니다.

URI 구조

예시:

• 사용자 정보: /users
• 특정 사용자: /users/123
• 사용자가 소유한 주문 목록: /users/123/orders

행위 (Methods)

자원에 대한 행위는 주로 HTTP 메소드를 사용하여 정의됩니다. 이 메소드들은 자원을 조작하는 데 사용됩니다.

• GET: 자원의 조회에 사용됩니다. 서버는 요청된 자원의 표현을 클라이언트에게 반환합니다.
• POST: 새로운 자원을 생성할 때 사용됩니다. POST 요청은 보통 서버에 새로운 자원을 추가하기 위해 사용됩니다.
• PUT: 자원의 전체 업데이트에 사용됩니다. PUT 요청은 지정된 URI의 자원을 요청 페이로드의 내용으로 대체합니다.
• DELETE: 자원의 삭제에 사용됩니다. 지정된 URI의 자원을 제거합니다.
• PATCH: 자원의 부분 업데이트에 사용됩니다. 수정하고자 하는 필드만을 포함하여 요청합니다.

표현 (Representations)

자원의 상태는 클라이언트에게 전달되는 데이터 형식인 "표현"을 통해 전달됩니다. REST API는 보통 JSON 또는 XML 형식을 사용하여 데이터를 표현합니다. 클라이언트는 HTTP 헤더를 통해 어떤 형식의 데이터를 받고 싶은지 서버에 알릴 수 있습니다.

예시:

• JSON 응답:

{
	"id": 123,
	"name": "John Doe",
	"orders": [
		{
			"orderId": 789,
			"amount": 150.0
		}
	]
}

자원 원형(Resource archetypes)

REST 각 자원의 구조와 작업을 설명하기 위해 자원 원형 개념이 도입되었습니다. 이러한 자원 원형은 자원을 분류하고, 해당 자원에 어떤 HTTP 메소드가 적용되어야 하는지 명확하게 합니다.

1. 문서(Document): 개별 문서를 나타내며, 특정 주제에 대한 정보를 하나의 엔티티로 표현합니다. 예를 들어, 사용자의 프로필이나 특정 주문에 대한 정보 등이 이에 해당합니다.

   • 예시 URI: /users/12345 또는 /orders/98765

2. 컬렉션(Collection): 동일한 유형의 문서들의 집합을 나타냅니다. 컬렉션 자체도 자원으로 간주되며, 컬렉션 내의 개별 항목에 대한 액세스를 제공합니다.

   • 예시 URI: /users 또는 /orders

3. 스토어(Store): 클라이언트가 관리하는 리소스 저장소입니다. 스토어는 클라이언트가 리소스를 생성하고 관리할 수 있도록 하며, 저장소 내의 리소스에 대한 키를 클라이언트가 지정할 수 있습니다.

   • 예시 URI: /fileStore에서 클라이언트가 파일 이름을 지정하여 파일을 저장하고 액세스할 수 있습니다.

4. 컨트롤러(Controller): 일반적인 문서, 컬렉션, 스토어가 아닌, 실행 가능한 함수를 추상화한 리소스입니다. 컨트롤러는 특정 작업을 수행하고, 종종 문서나 컬렉션의 상태를 변경하는 데 사용됩니다.

   • 예시 URI: /orders/12345/ship 또는 /processData (여기서 "ship"은 주문을 배송 처리하는 함수)

HTTP 메소드와의 관계

각 자원 원형은 특정 HTTP 메소드와 연결됩니다. 예를 들어:

• 문서와 스토어 자원은 일반적으로 GET, POST, PUT, DELETE 메소드를 사용하여 각각 조회, 생성, 업데이트, 삭제 작업을 수행할 수 있습니다.
• 컬렉션 자원은 GET (컬렉션 내 모든 항목 조회), POST (새 항목 추가) 등을 사용합니다.
• 컨트롤러 자원은 특정 작업을 수행하기 위해 POST 메소드를 사용하는 경우가 많습니다.

참조

REST API란? | IBM