Engineering

API 가이드 vs. API 스펙, 뭐가 다른거야?

2024년 9월 11일

final_섬네일민트2.png

들어가며

API(application programming interface)는 우리가 인지하지 못하는 동안에도 일상생활의 곳곳에 밀접하게 연관되어 있습니다. 날씨 정보 조회에서부터 소셜 미디어 로그인까지 우리가 의식하지 않는 순간에도 API를 호출하고 데이터를 주고받고 있는데요. 작년 TESLA가 서드 파티 애플리케이션을 지원하기 위한 공식 API와 API 문서를 공개하면서 이제 API가 전 산업분야에서 활발히 사용 중인 걸 알 수 있었습니다. 아카마이 테크놀로지가 발표한 조사에 따르면 API 호출로 인한 웹 트래픽이 전체 웹 트래픽의 83퍼센트를 차지한다고 합니다. 이렇게 API가 마치 물처럼 없어선 안 될 요소가 되면서 동시에 API 문서의 중요성도 함께 커지고 있습니다.

여러 서비스들의 기술 문서를 보다 보면 API 가이드 또는 API 명세, API 레퍼런스 같은 용어들을 자주 마주칠 수 있는데요. 과연 이 용어들이 같은 의미를 가지고 있을까요?

사실 API 문서와 API 스펙은 비슷해 보이지만 다른 의미를 가지고 있습니다. API 스펙(API specification)이란 무엇일까요? API 문서(API documentation)를 의미하는 것일까요?

API 문서? API 스펙?

API 가이드, API 레퍼런스는 모두 API 문서(API documentation)입니다. API 문서는 API 사용 방법을 주로 다룹니다. 독자는 개발자 또는 API를 사용하는 일반 사용자입니다. API 호출 시 필요한 파라미터와 반환되는 응답, 오류 메시지, JavaScript, Python과 같이 자주 사용되는 개발 언어로 작성된 샘플 코드 등을 제공해 독자가 읽고 쉽게 이해할 수 있도록 돕는 문서입니다. 따라서 잘 작성된 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의 동작 방식과 다른 API와 상호 작용에 대해 상세하게 기술한 문서입니다.

화면 캡처 2024-09-04 154738.png

API 스펙은 API를 맨 처음 개발할 때부터 API를 기술하는 API 문서를 제작하는 데 있어 가장 필수적인 도구입니다. API 스펙이 아주 잘 정립되어 있다면 생소한 코드를 분석하는 골치 아픈 일을 건너뛰고 API를 훨씬 더 일관되고 안정적으로 구현할 수 있습니다. 사실 ‘API 스펙’이란 개념이 등장하기 전엔, API 개발하는 과정은 팀마다 회사마다 제각각이고 질서가 없었는데요. 그 결과, 완성된 힘들게 개발한 API를 연동하는 것이 무척 어렵고 복잡하고 비효율적이었습니다. 이는 곧 서비스의 매력도를 크게 떨어뜨리는 결과를 가져오게 되죠.

비교_new1.png

OpenAPI의 등장

‘API 스펙’이란 개념이 주목받기 시작한 때는 2010년 지금은 너무나 잘 알려진 Swagger가 등장하면서부터입니다. Swagger는 API를 문서화하고, 정의하고 인터랙션 하기 위해 필요한 모든 것을 제공하는 오픈소스 소프트웨어 프레임워크인데요. 풀어서 설명하면, Swagger는 RESTful API(웹에서 사용되는 자원을 효율적이고 안정적으로 사용할 수 있게 하는 REST 원칙을 잘 따르는 API)를 설계하고, 빌드하고, 이에 대한 문서도 작성할 수 있도록 하는 도구입니다. 여기에 더해 빌드한 API를 호출해 볼수도 있습니다.

API를 작성할 수 있다는 점에는 Swagger는 API 정의 언어라고도 하는데요. 다음에 나올 내용에서 계속 등장하니 기억해 주시기 바랍니다. Swagger로 작성한 API 스펙인 Swagger Specification이 API 스펙의 표준으로 널리 사용되었는데, 이후 2015년 Swagger 개발사인 SmartBear가 Swagger Specification을 리눅스 재단 산하의 오픈API 이니셔티브 에 기부하면서 Swagger Specification은 OpenAPI Specification(OAS) 라는 공식 명칭을 가지게 되었고 OAS는 표준 API 스펙으로 자리잡게되었습니다. 오픈 API 이니셔티브는 API 기술하는 방식을 표준화하자는 목표 아래 현재도 활발하게 API 생태계 발전에 기여하고있습니다. 2024년 9월 기준, OAS는 버전 3.1.0 까지 업데이트되었습니다.

다시 말하자면 OpenAPI는 Swagger와 마찬가지로 API 정의 언어(API description language)이며, OpenAPI로 작성한 API 스펙을 OAS(OpenAPI Specification)라고 합니다.

OAS는 이제 API 스펙의 표준으로 인식되며 현재 가장 많이 사용되는 API 스펙입니다. OAS를 활용하면 기계가 인식할 수 있는 형태로 API를 설계할 수 있고, 더 나아가 API 문서와 클라이언트 SDK 등을 생성하고 인증과 오류 처리 방법, 보안과 같은 디테일한 정보도 기술할 수 있습니다.

TypeSpec의 등장

이렇게 OAS가 API 스펙의 표준으로 굳건하게 입지를 다지는 중에 최근 Microsoft가 새로운 API 정의 언어인 TypeSpec을 출시했습니다. TypeSpec은 Microsoft Graph 개발팀이 마치 코드를 작성하는 것처럼 유연하고 편리하게 API 스펙을 작성하고 싶다는 생각에서 탄생했습니다.

API 콘퍼런스인 Nordic APIs에서 Microsoft Azure SDK 팀리더는 무수히 많은 문서와 라이브러리를 일관되고 용이하게 관리하기 위해 API 정의 언어로 TypeSpec을 활용한다고 합니다. 내부에서 API와 SDK 문서를 일관되게 관리하기 위한 API 작성 가이드라인이 있지만, Azure 서비스가 급속하게 성장하다 보니 각기 다른 언어로 작성된 API 문서를 효율적으로 관리하기가 어려워졌고 이런 상황에서 TypeSpec으로 API를 정의하면 API 스펙을 크게 간소화할 수 있고, API 가이드라인을 재사용 가능한 코드로 만들면 신규인력도 이를 빠르고 쉽게 적용하여 API 문서를 작성할 수 있다고 하는데요.

마치 코드를 작성하는 것과 같이 API 스펙을 작성해서 Design-First 접근법(API 설계 시 API 스펙을 먼저 작성하는 접근법)을 실현하기 위해 TypeSpec을 활발히 사용 중이라고 밝혔습니다.

반복해서 나오는 API 정의 언어와 API 스펙의 개념을 구분하면 아래와 같습니다.

자산 2.png

그렇다면 OpenAPI와 TypeSpec으로 작성한 API 스펙이 어떻게 다른지 한번 살펴보겠습니다. 예로 아래와 같이 동작하는 API가 있습니다.

사용자 관리 API

사용자 목록 조회(List)
ID로 사용자 단일 조회(Read)
신규 사용자 생성(Create)
사용자 정보 수정(Update)
사용자 삭제(Delete)

OpenAPI vs TypeSpec

TypeSpec과 OpenAPI로 각각 사용자 관리 API 스펙을 작성하면 아래와 같습니다

이 두 API 정의 언어의 장점과 단점은 분명한데요. TypeSpec은 코드를 작성하는 것과 유사하게 API 스펙을 작성할 수 있고, OpenAPI 대비 좀 더 경량화된 언어인 반면, 아직 OpenAPI보다 지원하는 서드파티 툴이 적다는 단점이 있습니다. 또한 OpenAPI는 호환 가능한 툴이 매우 다양하고 관련 생태계가 활성화되어있지만 API의 규모가 커질수록 길이가 너무 길어지고 복잡해지는 단점을 가지고 있습니다.

TypeSpec은 OpenAPI를 완벽히 대체하기는 어려울 것이라는 의견도 있습니다만, 그보다 TypeSpec을 활용해 코드를 작성하는 것처럼 재사용 가능하고 확장 가능한 API 스펙을 만들 수 있고, OpenAPI 툴 체인과 쉽게 연동이 가능하여 이는 결국 API 생태계를 더욱 풍성하게 만들 것이란 의견이 많습니다.

TypeSpec과 OpenAPI와 같은 API 정의 언어로 API 스펙을 작성할 때 누릴 수 있는 이점을 정리해 보면 아래와 같습니다.

일관성
- API 스펙, 즉 API 규격이 잘 정립되어 있다면, 신규 API가 출시되었을 때, API 스펙에 부합하는지를 검증할 수 있습니다. 이로써 API의 작동 방식을 더욱 빠르고 쉽게 이해할 수 있습니다.
- API들이 일관된 규격에 맞게 설계되므로, 이는 백엔드 개발자와 프론트엔드 개발자 간 커뮤니케이션을 매끄럽게 만들어줍니다.
문서 자동화
- Swagger 같은 API 문서 자동화 툴과 호환할 수 있어, API 문서에 포함된 API 엔드포인트를 즉시 테스트해 볼 수 있습니다.
쉬운 유지 보수와 테스트
- 일관된 규격에 맞게 설계된 API는 물론 그렇지 않은 API보다 이해하기가 더 쉬우므로, API 업데이트 혹은 버전업을 더 빠르게 수행할 수 있습니다.

나가며

API 가이드와 API 스펙은 평소 자주 혼용되어 그 개념을 정확히 알고자 이렇게 기술 공유 글을 작성하게 되었는데요, 이번 계기로 API 스펙이 API 문서와 어떻게 다른지 알 수 있었습니다. 비즈니스 관점에서 잘 작성된 API 스펙과 API 가이드는 API가 약속한 대로 작동할 것이라는 계약서와 같은 역할을 하고 이는 신뢰성과도 직결되는데요, 더 나아가 완성도 있는 애플리케이션 구축의 토대가 된다는 점을 고려하면 앞으로 API 스펙의 중요성은 커질 것입니다. 긴 글 읽어주셔서 감사합니다.