API 제품 사양으로 프로토타입 사용

게시 됨: 2016-02-02

저는 SendGrid의 개발자 경험 제품 관리자로서 API와 관련된 기회, 기능 및 제품을 식별하는 임무를 맡고 있습니다. 제가 작업한 한 가지는 제품 아이디어를 다른 PM, 엔지니어 및 고객에게 보다 효과적으로 전달할 수 있는 방법을 식별하는 것입니다.

모놀리식 PRD(제품 요구 사항 문서)는 이를 수행하는 데 이상적이지 않으며 제품 사양과 동일한 정보를 포함하는 테스트 가능한 인터페이스가 강력한 대안이 될 수 있음을 배웠습니다. PRD의 문제는 종종 매우 크고 대부분이 텍스트라는 것입니다. 자리를 잃거나 정말 중요한 것을 놓치는 것은 너무 쉽습니다.

UX에 있는 우리 친구들은 인터페이스를 단순히 설명하는 문서나 와이어프레임이 아니라 터치하고 사용할 수 있는 클릭 가능한 인터페이스를 제공하는 Invision 과 같은 도구로 이 문제를 해결했습니다. API는 인터페이스이므로 문서에 있는 설명 텍스트와 JSON 대신 사양과 실시간으로 상호 작용할 수 있는 도구가 필요합니다.

요구사항 정의

제품 사양으로서 이 테스트 가능한 인터페이스는 어떤 모습이어야 합니까? 어떻게 작동할까요? 존재하는가?

Marty Cagan의 Inspired: How to Build Products Products Customers Love 의 18장, "제품 사양 재창조"를 읽으면서 제품 사양에 대한 Cagan의 요구 사항을 충족하는 도구를 공유하고 싶다는 것을 깨달았습니다. 제품 사양에 대한 그의 위시리스트와 사양에 따른 프로토타입 요구 사항에 대한 내 개인 목록입니다.

Cagan의 요구 사항*:

  • 사양은 전체 사용자 경험을 설명해야 합니다.
  • 사양은 소프트웨어의 동작을 정확하게 나타내야 합니다.
  • 모든 이해 관계자가 필요한 것을 얻을 수 있는 방식으로 제품을 전달할 수 있어야 합니다.
  • 사양이 바뀝니다
  • 모호성과 버전염을 줄이기 위해 사양의 단일 마스터 표현이 필요합니다.

케이건의 위시리스트*:

  • 다음과 같이 프로토타입을 보완해야 합니다.
    • 비즈니스 로직
    • 릴리스 요구 사항
    • 플랫폼 제공 요구 사항
    • 사용 사례
  • 프로토타입에 주석을 달 수 있기를 정말로 원합니다.

사양에 따른 프로토타입에 대한 내 요구 사항:

  • 프로토타입은 사양이어야 합니다.
  • 문서는 프로토타입에 통합되어야 합니다.
  • 이를 필요로 하는 회사의 모든 사람은 프로토타입과 문서에 액세스할 수 있어야 합니다.
  • 고객은 사용자 테스트를 위해 프로토타입의 기능적 부분에 액세스할 수 있어야 합니다.
  • 프로토타입은 사양을 대체해야 하며 완제품을 배선하지 않고도 의도한 기능에 가깝게 작동해야 합니다.
  • 프로토타입에 대한 변경 사항을 작성하고 기록하기 쉬워야 합니다.
  • 프로토타입에 액세스할 수 있는 모든 사람이 테스트할 수 있는 A/B 변형을 쉽게 만들 수 있어야 합니다.
  • 프로토타입에서 고객 문서를 쉽게 내보낼 수 있어야 합니다.

정지등 소개

위의 거의 모든 것을 충족시키는 내가 사용하고 있는 도구를 Stoplight.io 라고 합니다. API 문서 엔진과 웹 프록시의 핵심입니다. 이를 통해 Swagger 및 RAML을 모두 사양 엔진으로 사용하고 두 형식에서 가져오거나 내보낼 수 있는 기능이 있는 직관적인 UI를 사용하여 API를 정의할 수 있습니다.

StopLight는 문서화 도구이므로 엔드포인트에 대한 요청, 응답, 헤더 및 설명을 정의할 수 있습니다. 프록시 기능을 사용하면 API를 호출하고 호출이 사양과 일치하는지 확인하거나 끝점을 자동 검색하여 대부분의 문서가 자동으로 작성되도록 할 수 있습니다.

StopLight의 프록시에는 몇 가지 다른 절대적으로 놀라운 기능도 있습니다.

  • 제품이 완료되지 않았거나 요청을 프록시하지 않으려는 경우 엔드포인트에 모의 호출을 할 수 있는 기능.
  • 컴퓨터에서 프로토타입을 테스트하기 위한 로컬 서버입니다.
  • 인터넷에서 프로토타입을 테스트하기 위한 원격 서버입니다.
  • 프로토타입의 끝점이 호출되기 전 및/또는 후에 실행할 수 있는 코드를 정의하기 위해 Javascript로 작성된 미들웨어입니다.

내 위시리스트, Cagan의 사양 요구 사항 및 그의 희망 목록을 StopLight가 제공하는 기능과 비교하면 StopLight가 모든 필요와 욕구를 충족한다는 것을 알 수 있습니다.

  • 프로토타입 및 해당 기능에 대한 내부 전용 문서입니다.
  • 쉽게 액세스할 수 있는 기능의 전체 프로토타입입니다.
  • 사용자 테스트 및 피드백을 위해 다양한 기능을 전환할 수 있는 테스트 가능한 인터페이스입니다.
  • 특정 대화에 대한 프로토타입 버전을 쉽게 관리할 수 있으므로 거의 실시간으로 프로토타입의 기능을 수정하여 받은 피드백을 설명하고 확인할 수 있습니다.

StopLight의 작업 흐름은 간단하며 기술 능력에 관계없이 누구나 수행할 수 있습니다.

  • 새 프로젝트를 만듭니다.
  • 엔드포인트, 해당 매개변수, 요청 및 응답에 대한 정보를 클릭하고 입력하여 사양을 추가합니다.
  • 정의 화면에서 프로토타입에 대한 사양 정보를 추가합니다.
  • 선택적 기능이 있으면 미들웨어를 사용하여 추가하십시오.
  • 조롱을 켜십시오.
  • 모의 서버의 공개 URL을 복사/붙여넣기하고 피드백을 위해 공유하세요.

고객을 방문할 예정이고 프로토타입을 실시간으로 실험하려면 정의를 컴퓨터에 다운로드하고 방문 이름을 따서 명명된 새 프로젝트를 만들고 정의를 가져오기만 하면 됩니다. 이제 원래 프로토타입을 변경하지 않고도 원하는 모든 것을 변경할 수 있습니다. 돌아와서 아이디어를 병합하면 처음에 프로토타입을 만드는 것처럼 쉽게 변경할 수 있습니다.

개발자 경험 제품 관리자인 StopLight는 내 작업을 보다 효율적으로 수행하는 데 도움이 될 뿐만 아니라 사용이 매우 간단하며 문서가 고객 검증 단계 전에 시작되고 업데이트되기 때문에 API 문서화의 전달 준비 단계를 쉽게 만듭니다. 프로세스 전반에 걸쳐. StopLight가 제공하는 다른 많은 사용 사례와 기능이 있지만 이것이 내 작업에 가장 큰 영향을 미친 것일 수 있습니다.

*Cagan의 요구 사항과 위시리스트는 Inspired: How to Build Products Goods Love에서 직접 인용한 것입니다.