시스템 설계 치트 시트: API 스타일 - REST, GraphQL, WebSocket, Webhook, RPC/gRPC, SOAP

이것은 시스템 아키텍처 설계의 특정 주제의 주요 요점을 간략하게 다루는 일련의 기사의 연속입니다. 첫 번째 기사는 여기서 읽을 수 있습니다

API 아키텍처는 소프트웨어 구성 요소가 상호 작용하는 방식을 지정하는 일련의 규칙, 프로토콜 및 도구를 나타냅니다. API 아키텍처는 단순히 통신을 촉진하는 것이 아닙니다. 또한 이러한 통신이 효율적이고 안전하며 확장 가능하도록 보장하는 것도 중요합니다.

잘 설계된 API 아키텍처는 시스템 성능을 크게 향상시킬 수 있지만 잘못 설계된 API 아키텍처는 병목 현상, 보안 취약성 및 유지 관리의 악몽을 초래할 수 있습니다.

API 아키텍처의 다양한 스타일

가장 일반적인 API 디자인 스타일:

1. REST (Representational State Transfer)는 표준 방법과 HTTP 프로토콜을 사용하는 가장 많이 사용되는 스타일입니다. 이는 상태 비저장, 클라이언트-서버 아키텍처 및 캐시 가능성과 같은 원칙을 기반으로 합니다. 프런트엔드 클라이언트와 백엔드 서비스 간에 자주 사용됩니다.

   
   

2. GraphQL 은 API용 쿼리 언어입니다. 각 리소스에 대해 고정된 엔드포인트 세트를 노출하는 REST와 달리 GraphQL을 사용하면 클라이언트가 필요한 데이터를 정확하게 요청할 수 있으므로 과도한 가져오기가 줄어듭니다.

   
   

3. WebSocket은 TCP를 통한 양방향 통신을 허용하는 프로토콜입니다. 클라이언트는 웹 소켓을 사용하여 백엔드 시스템에서 실시간 업데이트를 받습니다.

   
   

4. 웹훅은 한 시스템이 특정 이벤트에 대해 실시간으로 다른 시스템에 알릴 수 있는 메커니즘입니다. 사용자 정의 HTTP 콜백입니다.

   
   

5. RPC(gRPC) 는 하나의 서비스가 네트워크의 다른 컴퓨터에 있는 서비스에 프로시저/메서드를 요청하는 데 사용할 수 있는 프로토콜입니다. 일반적으로 낮은 대기 시간, 고속 통신을 위해 설계됩니다.

   
   

6. SOAP 는 웹 서비스를 구현하기 위해 구조화된 정보를 교환하기 위한 프로토콜입니다. 이는 XML을 기반으로 하며 현재 레거시 프로토콜로 간주되는 견고성과 보안 기능으로 유명합니다.

모든 장단점 및 사용 사례와 함께 각 프로토콜을 개별적으로 살펴보겠습니다.

나머지

REST 는 표준 규칙과 프로토콜을 사용하여 이해하고 구현하기 쉬운 아키텍처 스타일입니다. 상태 비저장 특성과 표준 HTTP 메소드 사용으로 인해 웹 기반 API 구축에 널리 사용됩니다.

REST는 오랫동안 API 구축을 위한 사실상의 표준이었지만, GraphQL과 같은 다른 스타일이 등장하여 데이터 쿼리 및 조작을 위한 다양한 패러다임을 제공했습니다.

형식 : XML, JSON, HTML, 일반 텍스트

전송 프로토콜 : HTTP/HTTPS

주요 개념 및 특징

• Resource : REST에서는 모든 것이 리소스입니다. 리소스는 유형, 관련 데이터, 다른 리소스와의 관계 및 이에 대해 작동하는 메서드 집합이 포함된 개체입니다. 리소스는 URI(일반적으로 URL)로 식별됩니다.

  
  

• CRUD 작업 : REST 서비스는 리소스에 대한 CRUD(생성, 읽기, 업데이트, 삭제) 작업에 직접 매핑되는 경우가 많습니다.

  
  

• HTTP 방법 : REST 시스템은 표준 HTTP 방법을 사용합니다.

  • GET: 리소스를 검색합니다.

  • POST: 새 리소스를 만듭니다.

  • PUT/PATCH: 기존 리소스를 업데이트합니다.

  • DELETE: 리소스를 제거합니다.

    
    

• 상태 코드 : REST API는 표준 HTTP 상태 코드를 사용하여 API 요청의 성공 또는 실패를 나타냅니다.

  • 2xx - 승인 및 성공
    • 200 - 알았어
    • 201 - 생성됨
    • 202 - 수락됨
  • 3xx - 리디렉션
    • 301 - 영구 이전
    • 302 - 발견됨
    • 303 - 기타 참조
  • 4xx - 클라이언트 오류
    • 400 잘못된 요청
    • 401 - 승인되지 않음
    • 403 금지
    • 404 찾을 수 없음
    • 405 - 메서드가 허용되지 않음
  • 5xx - 서버 오류

    • 500 내부 서버 오류

    • 501 - 구현되지 않음

    • 502 - 잘못된 게이트웨이

    • 503 - 서비스를 사용할 수 없음

    • 504 게이트웨이 시간 초과

      
      

• Stateless : 클라이언트에서 서버로의 각 요청에는 요청을 이해하고 처리하는 데 필요한 모든 정보가 포함되어야 합니다. 서버는 요청 사이에 클라이언트 상태에 대한 어떤 것도 저장해서는 안 됩니다.

  
  

• 클라이언트-서버 : REST는 클라이언트-서버 모델을 기반으로 합니다. 클라이언트는 사용자 인터페이스와 경험을 담당하고, 서버는 요청 처리, 비즈니스 로직 처리, 데이터 저장을 담당합니다.

  
  

• Cacheable : 서버의 응답을 클라이언트가 캐시할 수 있습니다. 서버는 응답이 캐시 가능한지 여부를 나타내야 합니다.

  
  

• 계층화된 시스템(Layered System) : 클라이언트는 일반적으로 최종 서버에 직접 연결되어 있는지, 아니면 중개자에 연결되어 있는지 알 수 없습니다. 중간 서버는 로드 밸런싱을 활성화하고 공유 캐시를 제공하여 시스템 확장성을 향상시킬 수 있습니다.

  
  

• HATEOAS: 애플리케이션 엔진으로서의 하이퍼미디어 Stat는 서버가 응답에서 동적으로 제공하는 하이퍼미디어를 기반으로 클라이언트가 웹 애플리케이션과 상호 작용하고 탐색할 수 있도록 하는 REST 웹 서비스 원칙으로, 느슨한 결합과 검색 가능성을 촉진합니다.

사용 사례

• 웹 서비스 : 많은 웹 서비스는 REST API를 통해 기능을 공개하므로 타사 개발자가 서비스를 통합하고 확장할 수 있습니다.

• 모바일 애플리케이션 : 모바일 앱은 종종 REST API를 사용하여 백엔드 서버와 통신하여 데이터를 가져오고 보냅니다.

• SPA(단일 페이지 애플리케이션) : SPA는 REST API를 사용하여 전체 페이지를 새로 고칠 필요 없이 콘텐츠를 동적으로 로드합니다.

• 시스템 간 통합: 조직 내의 시스템은 REST API를 사용하여 데이터를 통신하고 공유할 수 있습니다.

예

요구

GET "/사용자/42"

응답

 { "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } }

GraphQL

GraphQL은 특히 복잡한 시스템이나 프런트엔드에 높은 유연성이 필요한 경우 API 구축에 대한 보다 유연하고 강력하며 효율적인 접근 방식을 제공합니다. 일부 책임을 서버에서 클라이언트로 전환하여 클라이언트가 데이터 요구 사항을 지정할 수 있도록 합니다.

모든 시나리오에서 REST를 대체하는 것은 아니지만 특히 애플리케이션이 더욱 네트워크화되고 분산됨에 따라 많은 상황에서 강력한 대안을 제공합니다.

형식 : JSON

전송 프로토콜 : HTTP/HTTPS

주요 개념 및 특징

• API용 쿼리 언어 : 클라이언트가 필요한 데이터를 요청할 수 있으므로 단일 요청으로 필요한 모든 정보를 얻을 수 있습니다.

• 유형 시스템 : GraphQL API는 엔드포인트가 아닌 유형 및 필드 측면에서 구성됩니다. API의 기능을 정의하기 위해 강력한 유형 시스템을 사용합니다. API에 노출된 모든 유형은 GraphQL SDL(스키마 정의 언어)을 사용하여 스키마에 기록됩니다.

• 단일 엔드포인트 : 서로 다른 리소스에 대해 여러 엔드포인트가 있을 수 있는 REST와 달리 GraphQL에서는 일반적으로 서비스의 전체 기능 세트를 표현하는 단일 엔드포인트를 노출합니다.

• 해석기 : 서버 측에서 해석기는 쿼리에 설명된 데이터를 수집합니다.

• 구독을 통한 실시간 업데이트 : GraphQL에는 데이터 쿼리 외에도 구독을 사용한 실시간 업데이트 지원 기능이 내장되어 있습니다.

• Introspective : GraphQL 서버가 지원하는 유형을 쿼리할 수 있습니다. 이를 통해 클라이언트와 서버 간에 강력한 계약이 생성되어 도구 사용과 더 나은 검증이 가능해집니다.

사용 사례

• 유연한 프런트엔드 : 대역폭이 중요한 애플리케이션(특히 모바일)의 경우 서버에서 가져오는 데이터를 최소화하려고 합니다.

• 마이크로서비스 집계 : 마이크로서비스가 여러 개인 경우 GraphQL 계층을 도입하여 이러한 서비스의 데이터를 통합 API로 집계할 수 있습니다.

• 실시간 애플리케이션 : GraphQL은 구독 시스템을 통해 채팅 애플리케이션, 라이브 스포츠 업데이트 등과 같이 실시간 데이터가 필요한 애플리케이션에 매우 적합할 수 있습니다.

• 버전 없는 API : REST를 사용하면 변경 사항이 도입되면 API 버전을 지정해야 하는 경우가 많습니다. GraphQL을 사용하면 클라이언트는 필요한 데이터만 요청하므로 새 필드나 유형을 추가해도 주요 변경 사항이 생성되지 않습니다.

예

요구

GET "/graphql?query=user(id:42){ 이름 역할 { id 이름 } }"

응답

 { "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } }

웹소켓

WebSocket은 단일 장기 연결을 통해 전이중 통신 채널을 제공하여 클라이언트와 서버 간의 실시간 데이터 교환을 허용합니다. 이는 대화형 고성능 웹 애플리케이션에 이상적입니다.

형식 : 바이너리

전송 프로토콜 : TCP

주요 개념 및 특징

• 지속적인 연결 : 기존 요청-응답 모델과 달리 WebSocket은 열려 있는 전이중 통신 채널을 제공하여 실시간 데이터 교환이 가능합니다.

• 업그레이드 핸드셰이크 : WebSocket은 HTTP 요청으로 시작되며, 서버가 지원하는 경우 WebSocket 연결로 업그레이드됩니다. 이는 `Upgrade` 헤더를 통해 수행됩니다.

• 프레임 : 연결이 설정되면 데이터가 프레임으로 전송됩니다. 텍스트와 바이너리 데이터 모두 이 프레임을 통해 전송될 수 있습니다.

• 낮은 대기 시간 : WebSocket을 사용하면 각 교환에 대해 새 연결을 여는 오버헤드 없이 클라이언트와 서버 간의 직접 통신이 가능합니다. 이로 인해 데이터 교환이 더 빨라집니다.

• 양방향 : 클라이언트와 서버 모두 서로 독립적으로 메시지를 보낼 수 있습니다.

• 오버헤드 감소 : 초기 연결 후 데이터 프레임 전송에 필요한 바이트 수가 줄어들어 HTTP 연결을 반복적으로 설정하는 것보다 오버헤드가 줄어들고 성능이 향상됩니다.

• 프로토콜 및 확장 : WebSocket은 하위 프로토콜 및 확장을 지원하여 기본 WebSocket 프로토콜 위에 표준화된 사용자 정의 프로토콜을 허용합니다.

사용 사례

• 온라인 게임 : 플레이어의 행동이 즉시 다른 플레이어에게 반영되어야 하는 실시간 멀티플레이어 게임입니다.

• 공동 작업 도구 : 여러 사용자가 동시에 문서를 편집하고 서로의 변경 사항을 실시간으로 확인할 수 있는 Google Docs와 같은 애플리케이션입니다.

• 금융 애플리케이션 : 주가를 실시간으로 업데이트해야 하는 주식 거래 플랫폼.

• 알림 : 소셜 미디어 플랫폼이나 메시징 앱과 같이 사용자가 실시간 알림을 받아야 하는 모든 애플리케이션입니다.

• 라이브 피드 : 새로운 게시물이나 업데이트가 사용자에게 실시간으로 스트리밍되는 뉴스 웹사이트 또는 소셜 미디어 플랫폼입니다.

예

요구

"ws://site:8181"을 얻습니다.

응답

HTTP/1.1 101 스위칭 프로토콜

웹훅

Webhook 은 특정 웹 애플리케이션 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백으로, 실시간 데이터 업데이트와 다양한 시스템 간의 통합을 가능하게 합니다.

형식 : XML, JSON, 일반 텍스트

전송 프로토콜 : HTTP/HTTPS

주요 개념 및 특징

• 이벤트 기반 : 웹후크는 일반적으로 이벤트가 발생했음을 나타내는 데 사용됩니다. 웹후크는 정기적으로 데이터를 요청하는 대신 데이터가 발생하는 대로 제공하여 기존 요청-응답 모델을 완전히 뒤집습니다.

• 콜백 메커니즘 : 웹후크는 기본적으로 사용자 정의 콜백 메커니즘입니다. 특정 이벤트가 발생하면 원본 사이트는 대상 사이트에서 제공한 URI에 대한 HTTP 콜백을 만들고 특정 작업을 수행합니다.

• 페이로드 : 웹훅이 트리거되면 소스 사이트에서 타겟 사이트로 데이터(페이로드)를 보냅니다. 이 데이터는 일반적으로 JSON 또는 XML 형식입니다.

• 실시간 : 웹후크를 사용하면 애플리케이션이 실시간 데이터를 얻을 수 있어 반응성이 뛰어납니다.

• 사용자 정의 가능 : 사용자 또는 개발자는 일반적으로 알림을 받고 싶은 특정 이벤트를 정의할 수 있습니다.

• 보안 : 웹후크에는 사용자 정의 HTTP 엔드포인트에 대한 콜백이 포함되므로 보안 문제가 발생할 수 있습니다. 엔드포인트가 안전하고, 데이터가 검증되고, 암호화될 수 있는지 확인하는 것이 중요합니다.

사용 사례

• CI/CD(지속적 통합 및 배포) : 코드가 푸시되거나 풀 요청이 병합될 때 빌드 및 배포를 트리거합니다.

• 콘텐츠 관리 시스템(CMS) : 콘텐츠가 업데이트, 게시 또는 삭제되면 다운스트림 시스템에 알립니다.

• 결제 게이트웨이 : 결제 성공, 거래 실패, 환불 등 거래 결과를 전자상거래 플랫폼에 알립니다.

• 소셜 미디어 통합 : 소셜 미디어 플랫폼의 새 게시물, 멘션 또는 기타 관련 이벤트에 대한 알림을 받습니다.

• IoT(사물 인터넷) : 장치나 센서는 웹후크를 트리거하여 특정 이벤트나 데이터 판독에 대해 다른 시스템이나 서비스에 알릴 수 있습니다.

예

요구

GET " https://external-site/webhooks?url=http://site/service-h/api&name=name "

응답

 { "webhook_id": 12 }

RPC 및 gRPC

RPC (Remote Procedure Call)는 프로그램이 다른 주소 공간에서 프로시저나 서브루틴을 실행할 수 있도록 하는 프로토콜로, 분산 시스템 간의 원활한 통신과 데이터 교환을 가능하게 합니다.

gRPC (Google RPC)는 전송을 위해 HTTP/2를 사용하고 인터페이스 설명 언어로 프로토콜 버퍼를 사용하는 RPC 위에 구축된 최신 오픈 소스 프레임워크로, 효율적이고 강력한 통신을 촉진하기 위해 인증, 로드 밸런싱 등과 같은 기능을 제공합니다. 마이크로서비스 사이.

RPC

형식 : JSON, XML, Protobuf, Thrift, FlatBuffers

전송 프로토콜 : 다양함

주요 개념 및 특징

• 정의 : RPC는 프로그램이 다른 주소 공간(일반적으로 공유 네트워크의 다른 컴퓨터)에서 프로시저(서브루틴)를 실행하도록 허용합니다. 이는 호출자의 컴퓨터가 아닌 다른 컴퓨터에서 수행되는 함수를 호출하는 것과 같습니다.

• 스텁(Stubs) : RPC 컨텍스트에서 스텁은 로컬 및 원격 프로시저 호출이 동일하게 표시되도록 허용하는 도구에 의해 생성된 코드 조각입니다. 클라이언트에는 원격 프로시저와 유사한 스텁이 있고, 서버에는 인수를 풀고 실제 프로시저를 호출한 다음 결과를 팩하여 다시 보내는 스텁이 있습니다.

• 기본적으로 동기식 : 기존 RPC 호출은 차단됩니다. 즉, 클라이언트가 서버에 요청을 보내고 서버의 응답을 기다리면서 차단됩니다.

• 언어 중립 : 많은 RPC 시스템은 작성된 언어에 관계없이 다양한 클라이언트 및 서버 구현이 통신할 수 있도록 허용합니다.

• 긴밀한 결합 : RPC에서는 클라이언트와 서버가 호출되는 프로시저, 해당 매개변수 및 반환 유형을 알아야 하는 경우가 많습니다.

사용 사례

• 분산 시스템 : RPC는 시스템의 일부가 서로 다른 시스템이나 네트워크에 분산되어 있지만 마치 로컬인 것처럼 통신해야 하는 분산 시스템에서 일반적으로 사용됩니다.

• 네트워크 파일 시스템 : NFS(네트워크 파일 시스템)는 원격으로 파일 작업을 수행하는 RPC의 예입니다.

예

요구

 { "method": "addUser", "params": [ "Alex" ] }

응답

 { "id": 42, "name": "Alex", "error": null }

gRPC

형식 : 프로토부프

전송 프로토콜 : HTTP/2

주요 개념 및 특징

• 정의 : gRPC는 Google에서 개발한 오픈소스 RPC 프레임워크입니다. 전송에는 HTTP/2를, 인터페이스 설명 언어로는 프로토콜 버퍼(Protobuf)를 사용하고 인증, 로드 밸런싱 기능 등을 제공합니다.

• 프로토콜 버퍼 : 구조화된 데이터를 직렬화하기 위한 언어 중립적이고 플랫폼 중립적이며 확장 가능한 메커니즘입니다. gRPC에서는 Protobuf를 사용하여 서비스 메서드와 메시지 유형을 정의합니다.

• 성능 : gRPC는 짧은 대기 시간과 높은 처리량의 통신을 위해 설계되었습니다. HTTP/2를 사용하면 단일 연결을 통해 여러 호출을 다중화하고 오버헤드를 줄일 수 있습니다.

• 스트리밍 : gRPC는 스트리밍 요청 및 응답을 지원하여 장기 연결, 실시간 업데이트 등과 같은 보다 복잡한 사용 사례를 허용합니다.

• 기한/시간 초과 : gRPC를 사용하면 클라이언트가 RPC가 완료될 때까지 기다리는 시간을 지정할 수 있습니다. 서버는 이를 확인하고 작업을 완료할지 또는 시간이 너무 오래 걸릴 경우 중단할지 결정할 수 있습니다.

• 플러그형 : gRPC는 플러그형 인증, 로드 밸런싱, 재시도 등을 지원하도록 설계되었습니다.

• 언어 중립 : RPC와 마찬가지로 gRPC는 언어에 구애받지 않습니다. 그러나 Protobuf 및 gRPC 도구를 사용하면 여러 언어로 클라이언트 및 서버 코드를 생성하는 것이 쉽습니다.

사용 사례

• 마이크로서비스 : gRPC는 성능 특성과 서비스 계약을 쉽게 정의할 수 있는 기능으로 인해 마이크로서비스 아키텍처에서 일반적으로 사용됩니다.

• 실시간 애플리케이션 : 스트리밍 지원을 고려할 때 gRPC는 서버가 실시간으로 클라이언트에 데이터를 푸시하는 실시간 애플리케이션에 적합합니다.

• 모바일 클라이언트 : gRPC의 성능 이점과 스트리밍 기능은 백엔드 서비스와 통신하는 모바일 클라이언트에 적합합니다.

예

 message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); }

비누

Simple Object Access Protocol의 약자인 SOAP 는 컴퓨터 네트워크에서 웹 서비스를 구현하기 위해 구조화된 정보를 교환하기 위한 프로토콜입니다. 서로 다른 운영 체제에서 실행되는 프로그램이 서로 통신할 수 있도록 하는 XML 기반 프로토콜입니다.

형식 : XML

전송 프로토콜 : HTTP/HTTPS, JMS, SMTP 등

주요 개념 및 특징

• XML 기반 : SOAP 메시지는 XML로 형식화되며 다음 요소를 포함합니다.

  • Envelope : XML 문서를 SOAP 메시지로 정의하는 SOAP 메시지의 루트 요소입니다.

  
  

  • 헤더 : 중간 지점이나 최종 끝점에서 메시지 처리에 사용되는 메시지의 선택적 속성을 포함합니다.

  
  

  • 본문 : 전송되는 메시지를 구성하는 XML 데이터를 포함합니다.

  
  

  • Fault : 메시지를 처리하는 동안 오류에 대한 정보를 제공하는 선택적 Fault 요소입니다.

    
    

• 중립성 : SOAP는 모든 프로그래밍 모델과 함께 사용할 수 있으며 특정 모델에 묶여 있지 않습니다.

• 독립성 : 모든 운영 체제와 언어에서 실행될 수 있습니다.

• Stateless : 클라이언트에서 서버로의 각 요청에는 요청을 이해하고 처리하는 데 필요한 모든 정보가 포함되어야 합니다.

• 내장된 오류 처리 : SOAP 메시지의 Fault 요소는 오류 보고에 사용됩니다.

• 표준화됨 : SOAP 사양 자체를 포함하여 잘 정의된 표준과 메시지 전달을 보장하는 WS-ReliableMessaging, 메시지 보안을 위한 WS-Security 등과 같은 관련 표준을 기반으로 작동합니다.

사용 사례

• 엔터프라이즈 애플리케이션 : SOAP는 견고성, 확장성, 방화벽 및 프록시 통과 기능으로 인해 엔터프라이즈 환경에서 자주 사용됩니다.

• 웹 서비스 : 많은 웹 서비스, 특히 오래된 웹 서비스는 SOAP를 사용합니다. 여기에는 Microsoft 및 IBM과 같은 주요 회사에서 제공하는 서비스가 포함됩니다.

• 금융 거래 : SOAP의 내장된 보안 및 확장성은 데이터 무결성과 보안이 가장 중요한 금융 거래에 적합한 선택입니다.

• 통신 : 통신 회사는 다양한 시스템이 안정적으로 통신해야 하는 청구와 같은 프로세스에 SOAP를 사용할 수 있습니다.

예

요구

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserRequest> <m:Name>Alex</m:Name> </m:AddUserRequest> </soap:Body> </soap:Envelope>

응답

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserResponse> <m:Id>42</m:Id> <m:Name>Alex</m:Name> </m:AddUserResponse> </soap:Body> </soap:Envelope>

결론

API 아키텍처 스타일의 환경은 다양하여 REST, SOAP, RPC 등과 같은 다양한 접근 방식을 제공하며 각각 고유한 장점과 사용 사례가 있으므로 개발자는 다양한 소프트웨어 간의 확장 가능하고 효율적이며 강력한 통합을 구축하는 데 가장 적합한 패러다임을 선택할 수 있습니다. 구성 요소 및 시스템.