API 설계란 무엇인가요?

API 설계에는 API 엔드포인트, 요청 및 응답 형식, 프로토콜, API가 다른 애플리케이션 및 소비자와 통신하는 방식에 대한 결정이 포함됩니다. API 설계는 API 거버넌스에서도 중요한 역할을 합니다.

API 거버넌스는 조직이 API를 개발, 배포 및 사용하는 방법을 지시하는 포괄적인 표준, 정책 및 관행 세트를 말합니다. 효과적인 API 설계는 API 작동 방식을 설명하는 강력한 최신 문서와 함께 이러한 미리 결정된 정책을 준수하는 API를 생성합니다. 그 결과 재사용성, 확장성, 호환성이 향상되고 최종 사용자에게 더 나은 사용자 경험을 제공하는 잘 설계된 API가 탄생했습니다.

API 설계에는 다양한 API 사용 사례와 다양한 접근 방식이 있으며, 일부 프로토콜, 아키텍처 스타일 및 언어는 다른 프로토콜보다 특정 작업이나 사용 사례에 더 적합합니다.

웹 API의 사용이 증가함에 따라 특정 프로토콜, 스타일, 표준 및 언어의 개발 및 사용으로 이어졌습니다. 이러한 구조는 사용자에게 허용되는 데이터 유형, 명령, 구문 등을 정의하는 일련의 매개변수 또는 API 사양을 제공합니다. 이러한 API 프로토콜은 사실상 표준화된 정보 교환을 촉진합니다.

일반적인 프로토콜, 아키텍처 스타일 및 언어는 다음과 같습니다.

• SOAP(단순 객체 액세스 프로토콜)
• 원격 프로시저 호출(RPC)
• WebSocket
• REST(표현 상태 전송)
• GraphQL

새 API에 대한 올바른 구조를 선택하는 것은 설계 프로세스의 중요한 측면입니다. 이러한 프로토콜, 아키텍처 스타일, 그리고 언어들은 서로 우열을 가리는 것이 아닙니다. 그들은 다른 작업을 위한 다른 툴입니다.

SOAP는 끝점에서 SMTP(Simple Mail Transfer Protocol) 및 HTTP(Hypertext Transfer Protocol)를 비롯한 다양한 통신 프로토콜을 통해 데이터를 보내고 받을 수 있도록 하는 간단한 XML 기반 메시징 프로토콜 사양입니다. SOAP는 독립적이므로 SOAP API가 서로 다른 환경에서 실행되거나 다른 언어로 작성된 앱 또는 소프트웨어 구성 요소 간에 정보를 공유할 수 있습니다.

다른 종류의 API에 비해 SOAP API는 보다 공식화되고 구조화된 방식으로 개발되는 경향이 있습니다. SOAP API는 1990년대부터 사용되어 왔습니다. 더 오래되고 더 확립된 형식이지만 REST와 같은 최신 아키텍처보다 느립니다. 

SOAP는 XML 형식으로 데이터를 인코딩하여 작동하며 다른 형식의 데이터 전송은 지원하지 않습니다. 반면, SOAP API는 메시지를 전송하기 위해 반드시 HTTP가 필요하지 않으므로 데이터 이동에 더 많은 유연성을 제공합니다. SOAP는 다른 프로토콜보다 더 안전한 것으로 간주되므로 민감한 데이터를 처리하는 시스템에 SOAP API가 적합합니다.

RPC(원격 프로시저 호출)는 운영 체제에서 사용되는 높은 수준의 통신 패러다임을 제공하는 프로토콜입니다. RPC는 네트워크 응용 프로그램을 지원하기 위해 특별히 설계된 논리적 클라이언트-서버 통신 시스템을 구현합니다. RPC 프로토콜을 사용하면 사용자가 프로시저가 로컬인 것처럼 원격 프로시저를 사용할 수 있습니다. 따라서 많은 클라이언트/서버 상호 작용 및 클라이언트/서버 상호 작용이 필요한 상황에 적합합니다.

RPC API는 XML-RPC, JSON-RPC 및 gRPC로 더 세분화할 수 있습니다. XML-RPC는 특정 XML 형식을 사용하여 데이터를 전송하는 원격 프로시저 호출입니다. SOAP API보다 오래되었지만 간단하고 가볍습니다. JSON-RPC는 JSON(JavaScript Object Notation)을 사용하여 데이터를 전송하는 원격 프로시저 호출입니다. JSON은 범용 데이터 구조를 사용하므로 모든 프로그래밍 언어와 함께 사용할 수 있습니다. 

gRPC는 Google에서 처음 개발한 고성능 오픈 소스 RPC 프레임워크입니다. gRPC는 네트워크 프로토콜 HTTP/2 및 프로토콜 버퍼 데이터 형식을 사용하며 일반적으로 마이크로 서비스 아키텍처에서 서비스를 연결하는 데 사용됩니다.

웹소켓 API를 사용하면 클라이언트와 서버 간의 양방향 통신이 가능합니다. 이 유형의 API는 매번 통신할 때마다 새로운 연결을 설정할 필요가 없으며, 일단 연결이 설정되면 지속적인 교환이 가능합니다. 따라서 웹 소켓 API는 실시간 커뮤니케이션에 이상적입니다. 

실시간 채팅, 실시간 위치 추적 및 데이터 브로드캐스팅은 모두 WebSocket API의 훌륭한 사용 사례입니다. WebSocket API는 변경할 때마다 새 연결을 생성할 필요 없이 실시간으로 업데이트할 수 있기 때문에 여러 장치 또는 시스템에서 데이터를 일관되고 최신 상태로 유지하는 방식인 데이터 동기화에도 유용합니다.

REST는 일련의 웹 API 아키텍처 원칙입니다. REST API(RESTful API라고도 함)는 특정 REST 아키텍처 제약 조건을 준수하는 API입니다. REST API는 GET, PUT, HEAD 및 DELETE와 같은 HTTP 요청을 사용하여 리소스와 상호 작용합니다. REST를 사용하면 데이터를 리소스로 사용할 수 있으며 각 리소스는 고유한 URI로 표시됩니다. 클라이언트는 해당 URI를 제공하여 리소스를 요청합니다. REST API는 상태 비저장 API로, 요청 사이에 클라이언트 데이터를 저장하지 않습니다.

RESTful API는 가볍고 유연하며 사용하기 쉽기 때문에 널리 사용됩니다. 일반 텍스트, HTML, YAML, XML 및 JSON과 같은 다양한 형식의 메시지 전송을 완벽하게 지원하며 캐싱도 지원합니다. 이렇게 하면 매우 다양한 상황에서 유용하지만 일부 스테이션에서는 작업을 효율적으로 완료하기 위해 보다 구체적인 언어나 프로토콜이 필요합니다.

GraphQL은 Meta가 2012년에 내부적으로 개발한 쿼리 언어 및 런타임으로 2015년 오픈 소스가 되었습니다. GraphQL을 사용하면 파라미터가 많은 복잡한 엔드포인트에 액세스할 필요 없이 단 몇 줄로 API 요청을 수행할 수 있습니다. 이 기능을 사용하면 API 쿼리, 특히 여러 리소스를 대상으로 하는 더 복잡하거나 구체적인 요청을 더 쉽게 생성하고 이에 응답할 수 있습니다.

Meta가 모바일 애플리케이션을 더 효율적으로 만들기 위해 이 쿼리 언어를 개발했다는 점을 감안할 때 GraphQL API가 모바일 애플리케이션에 유용하다는 것은 당연합니다. 단일 진입점을 제공함으로써 GraphQL API는 서버에 여러 요청을 할 필요 없이 데이터를 쿼리하여 로드 시간을 줄일 수 있습니다. 

API 설계 프로세스에는 다음과 같은 네 가지 주요 단계가 있습니다.

• 계획
• 개발
• 테스트
• 배

이러한 모든 단계에는 주요 API 이해관계자 간의 협업이 필요합니다. 일부 단계는 다른 단계보다 일부 이해 관계자에게 가장 적합하지만 API 설계는 프로세스 전반에 걸쳐 여전히 협업해야 합니다. 이를 통해 개발자는 프로그램에 필요하지 않은 추가 기능을 추가하지 않아도 되므로 개발 프로세스 전반의 속도를 높일 수 있습니다.

모든 프로젝트의 첫 번째 단계는 어떤 종류의 새로운 API를 만들 것인지에 대해 모든 사람의 참여를 유도하는 것입니다. 고객이 전자 상거래 환경에서 인터페이스할 수 있도록 설계된 공개 API는 워크플로에 내부적으로 사용하기 위한 API와 설계 및 기능 요구 사항이 다릅니다. 개발을 시작하기 전에 모든 이해관계자가 잠재적 API의 사용 사례를 이해하는 것이 중요합니다.

기업이 무엇을 구축하고 있는지 그리고 그 이유를 이해하면 개발자는 어떤 프로토콜을 사용해야 하는지를 포함하여 구축 방법에 대한 더 나은 아이디어를 얻을 수 있습니다. 예를 들어, 이 API가 실시간 통신을 필요로 한다면, 개발자들은 해당 목적에 적합한 프로토콜이기 때문에 WebSocket을 사용할 수 있다는 점을 알고 있습니다. 

이해관계자가 API가 무엇인지, 어떻게 작동하는지에 대한 명확한 비전을 갖게 되면 이제 API를 구축할 차례입니다. API 개발 과정에서 개발자는 API 엔드포인트를 정의합니다. API에 대한 데이터 모델을 설계합니다. API가 API 보안 정책을 준수하고 오류에 대한 표준 상태 코드를 반환하는지 확인합니다. 필요한 경우 HTTP 헤더, API 키, OAuth 또는 JWT(JSON 웹 토큰)와 같은 인증 메커니즘을 구현합니다. 오류 코드, 메시지 및 응답을 정의합니다.

개발 프로세스의 또 다른 부분은 문서입니다. API를 빌드하는 동안 모든 선택 사항은 사람이 읽을 수 있고 기계가 읽을 수 있는 문서에 캡처되어야 합니다. 사람이 읽을 수 있는 문서는 자연스럽고 이해하기 쉬운 언어로 작성됩니다. 기계가 읽을 수 있는 문서는 형식을 표준화하여 일관성을 유지하고 향후 시스템에 통합할 수 있도록 하는 OpenAPI 사양과 같은 API 사양을 준수해야 합니다.

API 설계는 매우 반복적인 프로세스일 수 있습니다. 특히 API가 민감한 데이터를 노출하는 경우 버그와 결함이 있는지 엄격하게 테스트하는 것이 중요합니다. 무언가를 구축한 후에는 의도한 대로 작동하는지 확인하는 것이 중요합니다. API를 테스트할 때 중요한 과정 중 하나는 모의 테스트이며, 이는 샘플 데이터를 사용해 모의 서버를 구성한 뒤 API가 엔드포인트와 올바르게 통신하고 예상한 결과를 반환하는지 확인하는 과정입니다. 

API 테스트와 함께 모의 작업을 수행할 수 있습니다. API 테스트에는 요청과 응답이 어떤 형태여야 하는지를 규정하는 계약 테스트, 단일 엔드포인트가 예상한 응답을 반환하는지를 확인하는 단위 테스트, API가 최대 트래픽 상황에서도 성능을 유지할 수 있는지를 확인하는 부하 테스트, 그리고 하나 이상의 API와 통신하는 사용자 여정을 검증하는 엔드 투 엔드 테스트가 포함됩니다. 테스트는 수동으로 수행하거나 자동화된 테스트 프레임워크를 구현하여 수행할 수 있습니다.

모든 것이 의도한 대로 작동하면 API를 릴리스하고 배포할 준비가 된 것입니다. 이때까지 다른 사용자와 해당 컴퓨터가 이 API를 컴퓨터 네트워크 환경에 적절하게 통합할 수 있도록 API 문서가 완성되는 것이 중요합니다. API가 출시되면 사용자가 이해관계자가 예상하지 못한 문제를 발견할 수 있습니다. API가 출시되기 전에 버전 관리 전략을 수립해두면 개발자가 애플리케이션을 업데이트해야 할 경우 명확하고 일관되게 업데이트 할 수 있어 유용합니다.

애플리케이션 개발을 위한 API 우선 접근 방식은 소프트웨어 개발 프로세스를 시작할 때 API 설계를 우선시하고 API를 통해 제공될 서비스로 애플리케이션을 구축합니다. 소프트웨어 개발 초기에 API 설계의 우선순위를 정하면 결과적으로 API가 더 재사용 가능하고, 안전하고, 효율적이고, 사용하기 쉽고, 조직의 목표에 더 잘 부합할 수 있습니다. 이 접근 방식은 개발자가 나중에 소프트웨어에 맞게 API를 만드는 코드 로직을 우선시하는 코드 우선 접근 방식과 반대됩니다. 

API 설계는 API 우선 접근 방식의 핵심입니다. API 우선에서 API는 애플리케이션 개발의 핵심이며 신중한 설계는 더 나은 성능과 더 가치 있는 애플리케이션 개발을 촉진합니다. 

강력한 API 설계 사례는 개발 및 성능 문제가 더 큰 문제로 확대되기 전에 발견하고 해결함으로써 개발자 경험과 최종 사용자 경험을 모두 개선하는 데 도움이 될 수 있습니다.

이해관계자는 개발 프로세스 초기부터 기업의 모든 앱이 서로 잘 통합되고 작동하도록 설정할 수 있습니다. 성공적으로 구현되면 포괄적인 문서가 포함된 API 우선 접근 방식을 통해 개발자는 이미 존재하는 기능을 다시 만드는 대신 기존 API를 재사용할 수 있습니다.

REST(또는 RESTful) API는 구조가 느슨합니다. 유일한 요구 사항은 아키텍처 제약 조건이라고도 하는 다음 6가지 REST 설계 원칙(균일한 인터페이스, 클라이언트/서버 분리, 상태 비저장, 캐시 가능성, 계층화된 시스템 아키텍처 및 선택적으로 주문형 코드)에 부합해야 한다는 것입니다. 

이러한 아키텍처 제약으로 인해 RESTful API는 API 우선 접근 방식에 매우 적합합니다. 클라이언트/서버 분리 및 상태 비저장은 특히 유용합니다. 

RESTful API에서 클라이언트와 서버 애플리케이션은 서로 독립적이어야 합니다. 클라이언트 애플리케이션이 알아야 하는 유일한 정보는 요청된 리소스의 URI(Uniform Resource Identifier)입니다. 클라이언트 애플리케이션은 다른 방식으로 서버 애플리케이션과 상호 작용할 수 없습니다. 

REST API는 무상태성이기 때문에 각 요청에는 처리에 필요한 모든 정보가 포함되어야 합니다. 즉, REST API에는 서버 측 세션이 필요하지 않다는 의미입니다. 이러한 제약 조건은 이러한 API를 기업의 서버와 독립적으로 렌더링하여 API 설계에 영향을 주지 않고 클라이언트 및 서버 측 애플리케이션을 서로 다른 언어와 프로토콜로 작성할 수 있는 유연성을 제공합니다.

RESTful API는 확장 가능하고 가볍기 때문에 API 우선 환경에도 적합합니다. 클라이언트와 서버를 분리하면 RESTful API가 과거 클라이언트 요청 정보를 유지할 필요가 없어 통신 병목 현상이 줄어들기 때문에 확장성이 향상됩니다. 효과적인 캐싱은 또한 클라이언트/서버 상호 작용을 줄일 수 있으며 이는 확장성의 또 다른 장점입니다. RESTful API는 메시지 전송에 HTTP 형식을 사용하므로 여러 형식의 데이터 전송을 허용할 수 있습니다. 이것은 새로운 환경으로의 통합을 단순화할 수 있습니다.

마이크로서비스 아키텍처는 하나의 애플리케이션이 느슨하게 결합되고 독립적으로 배포할 수 있는 여러 작은 구성 요소 또는 서비스로 구성된 클라우드 네이티브 아키텍처 스타일입니다. REST API는 이러한 소규모 서비스 간의 통신을 활성화하는 데 자주 사용됩니다.

API 우선 접근 방식은 API가 서비스를 함께 연결하는 데 사용되기 때문에 마이크로 서비스 아키텍처 스키마와 잘 맞습니다. API 설계가 조직 내에서 우선시되고 API가 서로 원활하게 통신하도록 설계되면 개발자는 이러한 서비스를 더 큰 애플리케이션으로 함께 패키징하면서 시간을 절약할 수 있습니다. 

엔터프라이즈 API에서 최대한의 가치를 창출하기 위해 조직은 종종 다음을 강조합니다.

• API 거버넌스 및 문서
• 이해관계자 피드백 수집
• 적절한 인증
• 버전 관리
• 오류 메시지 표준화
• 확장 및 컨텍스트
• 일관성

이러한 원칙은 API 설계 프로세스 전반에 걸쳐 모든 이해관계자에게 정보를 제공하고 API가 조직의 목표 및 전략에 부합하는지 확인하는 데 도움이 됩니다.  

API 거버넌스 및 문서: 문서 조직 전체의 API 거버넌스 및 문서 전략을 일찍 수립하면 일관성을 촉진하고 기업의 API 포트폴리오를 더 쉽게 탐색할 수 있습니다. 예를 들어, 조직은 모든 엔터프라이즈 API가 업계 전반의 표준을 준수하도록 OpenAPI와 같은 사양을 채택하도록 선택할 수 있습니다. 어쨌든 적절하고 일관된 거버넌스 및 문서를 유지하면 새로운 API 사용자가 API와 해당 기능을 빠르게 이해할 수 있습니다. 

이해관계자 피드백 수집: 핵심 이해관계자와 API 소비자의 초기 의견은 개발자가 개발 프로세스 전반에 걸쳐 올바른 방향으로 나아갈 수 있도록 도와줍니다. 커뮤니케이션이 원활하지 않으면 API 개발이 지연되고 API의 가치가 떨어질 수 있습니다.

적절한 인증 및 API 보안: 조직에서는 API와 민감한 데이터를 보호하기 위해 API 요청에 대한 유효성 검사를 제공하는 인증 기술을 구현합니다. API 키, OAuth 및 JSON 웹 토큰(JWT)과 같은 인증 메커니즘은 데이터 및 API 트래픽을 보호하는 다양한 방법을 제공합니다. 클라이언트와 서버 간의 이동을 위해 데이터를 인코딩하는 프로세스인 API 암호화도 데이터와 API를 보호하는 데 사용됩니다.

테스트 및 버전 관리: API 테스트에는 API가 배포되기 전에 문제를 식별하기 위해 긍정적인 시나리오와 부정적인 다양한 시나리오를 다루는 것이 포함됩니다. API는 이 테스트 과정에서 발전하며 개발자는 버그를 수정하거나 성능을 개선하는 새 버전을 만듭니다. 개발자가 API에 새로운 기능을 추가하는 등 다른 이유로도 새 API 버전이 출시됩니다. 버전 관리란 개발자가 API의 변경 사항을 관리하고 , 변경 사항을 투명하게 만들고, 업데이트가 현재 사용자에게 방해가 되지 않도록 하는 방법입니다.

개발이 본격적으로 시작되기 전에 URL 기반 버전 관리 또는 헤더 기반 버전 관리와 같은 버전 관리 메커니즘을 정의하는 것이 유용합니다. 

오류 메시지 표준화: 적절한 오류 처리는 문제가 발생할 때 문제 해결에 도움이 되므로 API 소비자의 경험을 향상시킵니다. 오류 코드, 메시지 및 응답은 오류의 특성을 정확하게 설명하고 명확하고 일관성을 유지해야 합니다.

컨텍스트 및 제약 조건: 모든 API는 빌드 방법과 기능을 결정하는 특정 컨텍스트에 존재합니다. 경쟁 프로젝트 마감일, 예상 트래픽 볼륨, 기업이 API 우선인지 코드 우선인지에 따라 결과 API가 형성될 수 있습니다. 모든 이해관계자가 개발 과정에서 정보에 입각한 결정을 내릴 수 있도록 이 정보를 알고 있는 것이 중요합니다.

일관성: 무엇보다도 모든 것을 일관되게 유지하면 일반적으로 더 나은 API 설계로 이어집니다. API 설계의 일관성은 단순한 버전 관리 및 오류 코드 그 이상입니다. 엔드포인트를 정의할 때 명명 규칙을 일관되게 유지하면 엔드포인트를 더 쉽게 식별할 수 있습니다. API에 특정 요청을 할 때 매번 동일한 방식으로 해결해야 합니다. API 환경 전반에 걸쳐 모든 것이 일관되면 향후 사용자가 이해할 수 있도록 API를 문서화하는 것도 더 쉽습니다.