소식

Jul 04, 2023

API 디자인 리뷰가 사라졌습니다. API 디자인 리뷰 만세!

InfoQ 홈페이지 기사 API 디자인

InfoQ 홈페이지 기사 API 디자인 리뷰가 사라졌습니다. API 디자인 리뷰 만세!

2023년 5월 22일 8분 분량의 읽기

~에 의해

제이슨 하몬

검토자

토마스 베츠

API를 대규모로 설계하는 과정에서는 일관성을 유지하기 위한 의도적인 노력이 필요합니다. 여러 API와 실제 플랫폼처럼 느껴지는 것의 주요 차이점은 일관성입니다. 이 경우 일관성이란 단순히 여러 API를 사용하는 경우 명명 규칙, 페이징과 같은 상호 작용 패턴, 인증 메커니즘과 같은 요소가 전반적으로 표준임을 의미합니다.

전통적으로 검토 위원회는 개발이 완료되었다고 생각될 때 지연을 유발하는 발견으로 API 개발자에게 충격을 주었습니다. 더 나쁜 것은 위원회의 설계가 인계되어 진행이 지연되거나 개발자가 고통을 완전히 피하기 위해 프로세스를 회피하는 방법을 찾도록 장려할 수 있다는 것입니다.

최신 플랫폼을 진정으로 활용하려면 분산형 거버넌스를 통한 활성화가 훨씬 더 확장 가능하고 매력적인 접근 방식입니다. 이는 단순히 각 도메인 또는 기능 영역에 표준 및 전체 아키텍처에 대한 교육을 받은 주제 전문가가 API 개발자에게 유용한 가이드가 된다는 것을 의미합니다.

신원을 보호하세요. 안전한 디지털 서비스. 웹 및 모바일 애플리케이션에 대한 확장 가능하고 안전한 사용자 액세스를 지원합니다. 무료 평가판을 시작하세요.

더 중요한 것은 대량 개발이 완료되기 전에 API 설계에 동의하면 제공 기간을 위험에 빠뜨리는 막판 발견(종종 설계 우선 접근 방식이라고도 함)을 피할 수 있다는 것입니다. OpenAPI(HTTP/"REST" API의 사실상 표준)와 같은 사양 형식을 사용하면 개발 전에 API를 정의할 수 있는 기능이 제공되므로 문제를 훨씬 더 일찍 정렬하고 식별할 수 있습니다.

이러한 맥락을 염두에 두고 API 디자인 검토를 수행하는 방법, 프로세스를 개발하고 조직이 장기간의 일정과 개발자 참여 부족을 방지하도록 준비하는 방법을 자세히 살펴보겠습니다.

원활한 프로세스를 보장하기 위한 몇 가지 주요 전제 조건은 다음과 같습니다.

API 사용은 매우 정제된 경험이므로 언어의 영향은 대부분의 다른 디자인 영역보다 불균형적으로 높습니다. 각 팀 구성원은 다양한 용어를 정의하고 설명하는 방식이 조금씩 다를 수 있으며, 이는 API 팀의 혼란과 생산성 저하로 나타납니다.

API 포털/문서는 훌륭한 개발자 경험에 필수적이지만, 잘 설계된 API는 많이 생각할 필요 없이 대부분의 내용을 전달해야 합니다. 용어가 소비자에게 친숙하고 상호 작용 패턴이 분명하다면 경험은 빠르고 고통스럽지 않을 수 있습니다. 일관성은 여러 API와 하나의 플랫폼처럼 느껴지는 것 사이의 경험의 주요 차이점입니다.

API 프로그램 및 거버넌스 프로세스를 설정할 때 공유 언어로 시작하세요. 처음에는 불가능해 보일 수 있지만 플랫폼에 대한 고객 중심의 공유 어휘/문법을 정의하는 것은 필수적이며 조직의 전반적인 가속기입니다. 많은 용어가 회사 내부에서 다양한 의미를 가질 수 있으며, 설상가상으로 이러한 용어는 최종 소비자가 인식하지도 못하는 경우가 많습니다.

이 숙제를 미리 수행하면 API 설계 중에 이름 지정에 대한 충돌을 피할 수 있습니다. 관련 이해관계자와 각 도메인을 통해 작업하여 공유 용어를 정의하고 API 디자이너에 대한 광범위한 가용성과 인식을 보장합니다. 그리고 내부적으로 표준화된 용어를 정했다면, 외부 요구사항에도 맞는지 확인하는 것을 잊지 마세요. 고객 언어를 사용하고 API 개발에 대한 고객 중심 관점을 가지면 팀이 익숙하지 않은 기술 용어로 고객을 혼동하는 것을 방지할 수 있으므로 내부 이해와 외부 이해가 동기화되도록 할 수 있습니다.