API.md

API

API란?

• SW 간 데이터를 주고받기 위한 명세
• 서버 측에서는 특정 데이터 입력에 대해 어떤 데이터 출력을 제공할 것인지 명시
• 클라이언트 측에서는 정해진 명세에 따라 데이터를 보내고 결과를 받아 사용
• 현재 주로 사용되는 API 종류에는 아래와 같은 것들이 있음 (역사 순)
  • SOAP API
  • REST API
  • GraphQL
  • gRPC
• 왜 통신 규약을 표준화하려고 하는가?
  • 모두 다른 API 명세를 사용한다면, 다른 곳의 API를 사용하기 위해 명세를 확인할 때 이 명세를 이해하기 위해 많은 시간을 사용하게 됨
    • 명세가 어떤 기준으로 작성되었는지를 먼저 이해해야 하기 때문
  • 하지만 명세를 잘 알려진 공통적 포맷으로 다루면? API 자체에 대해 이해하는 데에만 집중하면 됨
    • 잘 알려진 아키텍처나 디자인 패턴을 적용하는 이유와 같다고 보면 될듯

SOAP API

• SOAP란 - XML 기반의 통신 프로토콜
• 원하는 데이터 획득을 위한 부가 정보를 XML 형식으로 request body에 담아 요청하고, 서버 측에서 제공하는 XML 내에서 원하는 태그의 값을 파싱해서 사용하는 방식으로 통신
• 주로 POST 메서드로 요청이 이루어짐

장점

• 높은 보안 수준
  • WS-Security와 같은 보안 프로토콜을 지원
  • 트랜잭션을 안전하게 처리하는 프로토콜도 지원
  • Stateful하기 때문에, 트랜잭션 단위의 처리에 더 유
  • 이러한 보안 수준 때문에 금융, 의료 등 중요한 정보를 다루는 서비스에서는 여전히 SOAP을 이용하기도 함

단점

• 한 번에 많은 내용을 담은 데이터(XML)가 오가므로 통신 속도가 느림
• Stateful하므로 서버 확장이 어려움
• 사람이 읽기 어려움
• 캐싱하기 어려움

REST API

• REST란 - API 설계를 위한 일종의 아키텍처 스타일
• URI로 작업을, HTTP Method로 행위를 나타냄

장점

• 가벼움
• 데이터 형식에 구애받지 않음 (XML, JSON, 이미지 등 다양한 것들을 주고받을 수 있음)
• Stateless 하므로 확장성이 좋음
• 캐싱에 용이함

단점

• 명확한 표준이 없어 사용 방법이 제각각일 수 있음
  • 실제로도 REST 규약을 제대로 준수하지 않고 애매하게 사용하고 있는 곳이 많음
• 자원의 위치를 나타내지만, 이를 통해 어떤 데이터들이 제공되는지를 알기는 어려움
  • /api/books/1 이라는 URI를 통해 1번 책에 대한 정보를 얻겠다는 것은 예측할 수 있으나 그 책의 어떤 정보들을 줄 건지는 바로 알기 어려움
• 복잡한 데이터를 다루기 어려울 수 있음
  • 보통 이러한 경우 제공할 데이터의 단순화를 위해 여러 엔드포인트로 쪼개고 클라이언트 측에서 여러 번 API를 호출하도록 하는데, 이 경우 여러 번의 통신이 발생한다는 비효율성이 존재
    • 이를 Under fetching 문제라고 함
• 원하는 데이터만 가져오기 어려움
  • book의 정보 중 저자와 총 페이지 수만 가져오고 싶다고 해도, API에서 줄거리, 가격 등 더 많은 데이터를 제공하면 데이터를 가져와놓고(통신 비용) 사용하지는 않게 됨
    • 이를 Over fetching 문제라고 함
• 보안이 강제되지 않기 때문에 설계 측에서 보안 설정을 제대로 하지 않으면 중간자 공격이나 XSS, CSRF 등 대표적 웹 공격을 당할 수 있음
• 즉, REST는 전반적으로 자유도가 높기 때문에 얻는 장점들이 많으나, 그만큼 제대로 잘 알고 사용하지 못하면 위험하기도 하고 장점을 잘 누리기도 어렵다는 특징을 가짐

GraphQL

• GraphQL이란 - REST의 Under fetching, Over fetching 문제의 해결안으로 떠오른 질의 언어
• 특정 데이터를 얻기 위한 쿼리를 작성해 요청하면 원하는 데이터만 응답으로 받을 수 있음

장점

• 복잡한 데이터를 효율적으로 얻을 수 있으며, 원하는 일부 데이터를 얻기에도 용이함
• Subscription 기능을 이용하면 WebSocket을 더 간편하게 이용할 수 있음

단점

• 캐싱이 어려움
  • 엔드포인트 당 응답 형식이 정해져있는 REST와 달리, GraphQL은 클라이언트가 요청한 만큼의 데이터만 제공하므로 응답 형식이 매우 다양함. 이 때문에, 캐싱이 어려움
• 서버에 부하를 줄 수 있음
  • 클라이언트가 어떤 데이터를 요구하냐에 따라 실행되는 쿼리가 바뀌고, 복잡한 연산을 요구하는 경우 이 요청이 서버에 부하를 줄 수 있음
• 보안에 유의해야 함
  • 쿼리를 통해 제공되어서는 안 되는 민감 정보가 제공될 수도, 불변인 데이터가 변경될 수도 있음
• 즉, GraphQL은 전반적으로 클라이언트에게 너무 많은 권한을 부여함에 따라 요청-응답 형식을 자율화했으나 클라이언트 측의 오남용으로 인한 보안 문제 또는 성능 문제가 발생할 수 있음에 유의해야 함

gRPC

• RPC란 - Remote Procedure Call, 즉 원격의 프로시저(기능)을 호출하는 통신 기술
• gRPC는 그 중 가장 널리 사용되는 RPC 프레임워크로, 구글에서 개발
• 프로토콜 버퍼(protobuf) 기반으로 클라이언트-서버 간에 미리 사양을 합의하고, 이를 통해 통신

장점

• JSON 기반의 REST 보다도 데이터의 사이즈를 줄일 수 있음
  • protobuf를 통해 키값을 간소화, 데이터의 바이너리 직렬화 등이 적용됨
• HTTP/2 기반으로 HTTP/2의 이점을 누릴 수 있음
  • 커넥션의 지속, HOL 방지와 병렬화, 서버로부터의 데이터 전송(양방향 전송 가능) 등
• TLS를 통한 암호화
  • 데이터를 암호화해 탈취/변조를 막음
• 즉, gRPC는 REST보다도 더 데이터를 간소화하고, 데이터의 효율적 통신이나 보안 체계를 표준화한 기술이라고 볼 수 있음

단점

• HTTP/2를 기반으로 하기 때문에, 이를 지원하지 않는 환경에서 사용하기 어려움
  • 일부 브라우저가 이에 해당하기 때문에, 아직 클라이언트-서버 간 통신은 gRPC로 대체하기에 어려움이 있음
  • 이 때문에 대부분 서버 투 서버 통신 중 효율성이 중시되는 곳에 도입됨. MSA 아키텍처를 사용하는 경우 서버 투 서버 통신이 많아지므로 gRPC가 각광받고 있음

Reference

• https://www.youtube.com/@yalco-coding