API·연동

이 카테고리에 속하는 도구

관련된 네 가지 일이 여기에 있습니다. 요청을 직접 만들고 테스트하기. 다른 사람이 쓸 수 있도록 인터페이스를 문서화하기. 여러 서비스 앞에 게이트웨이를 두어 키, 속도 제한, 할당량, 버전이 어디서나 같게 동작하게 하기. 서로 대화하도록 설계되지 않은 제품 사이에서 데이터를 옮기기.

앞의 셋은 API를 출시하는 팀을 위한 것입니다. 네 번째는 구매한 도구들을 이어 붙이는 모든 사람을 위한 것입니다. 두 부류가 모두 이 선반에 오기 때문에 제품들이 서로 그렇게 다르게 생겼습니다.

코드가 전혀 들어가지 않는 순수한 시각적 자동화는 노코드·자동화에 속합니다. 운영 중인 서비스의 알림은 모니터링입니다.

클라이언트, 그리고 이제 무엇이 이들을 가르는가

클라이언트는 모두 요청을 보내고 응답을 보여 줍니다. 차이는 그보다 깊은 곳에 있습니다.

먼저 환경 처리입니다. 로컬, 스테이징, 프로덕션, 그리고 동료가 노트북에서 돌리는 환경을 아무도 URL을 손으로 고치지 않고 깔끔하게 전환할 수 있어야 합니다. 그다음 스크립팅으로, 매일 아침 토큰을 붙여 넣는 대신 요청 전에 토큰을 가져올 수 있어야 합니다. 그다음 테스트 단언으로, 컬렉션을 빌드 서버가 실행할 수 있는 무언가로 만듭니다.

협업은 의견이 갈리는 부분입니다. 클라우드 동기화는 편리하지만 요청 이력이 남의 서버에 올라갑니다. 파일 기반 도구는 컬렉션을 코드 옆 저장소에 두기 때문에 변경이 다른 변경처럼 검토되고, 떠나는 직원과 함께 워크스페이스가 사라지지 않습니다.

어느 쪽이든 시크릿이 어디 있는지 물어보세요. 내보낸 컬렉션에 적힌 키는 공개 저장소로 가는 표준 경로입니다.

썩지 않는 문서

손으로 쓴 문서는 한 분기 안에 낡습니다. 살아남는 유일한 방식은 코드와 함께 있고 코드가 병합될 때 다시 빌드되는 명세에서 생성하는 것입니다.

세 가지를 확인하세요. 제품이 변환 단계 없이 내 명세 형식을 읽는지, 페이지에서 예제를 바로 실행할 수 있는지, 아직 쓰는 사람들을 위해 이전 버전이 계속 게시되는지입니다.

변경 이력은 디자인보다 중요합니다. 소비자는 무엇이 언제 깨졌는지 알아야 하고, 어떤 스타일링도 그것을 대신하지 못합니다.

게이트웨이, 그리고 언제 그만한 가치가 있는가

서비스가 하나뿐이라면 게이트웨이는 거의 필요 없습니다. 인증, 속도 제한, 할당량, 버전 관리가 여러 서비스에 걸쳐 똑같이 동작해야 하는 순간부터 필요가 생깁니다.

그 시점의 질문은 이렇습니다. 어디서 실행되고 지연 시간이 얼마나 늘어나는지, 한도를 어떻게 정의하는지, 한도에 걸리면 호출자에게 무엇이 보이는지, 다운타임 없이 키를 교체할 수 있는지, 로그에 무엇이 담기는지. 트래픽을 종단하는 모든 것은 그 자체로 가용성 위험이 되므로, 게이트웨이 자체가 장애를 일으키면 어떻게 되는지 물어보세요.

요금이 계량하는 것

• 사용자 수는 클라이언트와 문서 제품에 적용되며, 읽기 전용 검토자는 무료인 경우가 있습니다.
• 작업 또는 실행 수는 연동 플랫폼에서 워크플로 단위가 아니라 단계 단위로 집계합니다.
• 호출 또는 대역폭은 게이트웨이에서 계량하며, 캐시된 것은 별도 요율입니다.
• 보존 기간은 실행 이력에 대한 것으로, 입문 요금제에서는 짧고 필요한 순간에 딱 그만큼 짧습니다.
• 커넥터는 프리미엄 항목이 견적받은 요금제보다 한 단계 위에 놓여 있습니다.

작업 단위 과금은 계약 전에 계산해 봐야 합니다. 10분마다 실행되는 6단계 워크플로는 한 달에 작업 하나가 아니며, 그 숫자에 놀란 팀이 많습니다. 다른 카테고리에서도 비슷한 모양의 놀라움이 요금 페이지가 감추는 것에 모여 있습니다.

시험해 볼 것

이미 운영 중인 실제 연동 하나를 상대편이 오류를 반환하는 부분까지 포함해서 처음부터 끝까지 다시 만들어 보세요.

재시도, 중복 전달, 멈춰 버린 외부 서비스, 필드가 빠져서 도착한 페이로드를 도구가 어떻게 처리하는지 지켜보세요. 잘 만든 제품은 원인을 고친 뒤 실패한 실행을 다시 재생하게 해 줍니다. 부실한 제품은 조용히 잃어버리고, 고객이 알려 줄 때까지 아무 말도 하지 않습니다.

그다음 나가는 길을 확인하세요. 컬렉션, 명세, 워크플로 정의를 읽을 수 있는 파일로 내보낼 수 있어야 합니다. 워크스페이스 안에 갇힌 것은 두 번 하게 될 작업입니다.

문서, 버전 관리, 소비자 유지하기

사용자가 있는 인터페이스는 약속이며, 이 카테고리의 어려움 대부분은 그 약속을 깨지 않고 인터페이스를 바꾸는 데서 나옵니다.

첫 외부 소비자가 오기 전에 버전 관리 방식을 정하세요. 나중에 끼워 넣으려면 모두에게 한꺼번에 바꿔 달라고 요청해야 합니다. 방식이 무엇이든 무엇이 언제 바뀌었는지 게시하고, 폐기 예고 기간은 주 단위가 아니라 월 단위로 주세요.

오류에도 성공만큼 신경 쓰세요. 무엇이 잘못됐는지, 어떤 필드가 원인인지, 다음에 무엇을 해야 하는지 알려 주는 응답이 어떤 설명문보다 많은 지원 요청을 줄입니다.

그다음 신입의 눈으로 직접 쓴 문서를 읽어 보세요. 가장 빠른 개선은 보통 참조 표가 아니라 페이지 맨 위의 동작하는 예제입니다.