솔로 생활에서 벗어나기: Postman과 함께 API 개발에 공동작업하는 방법 배우기

API 개발은 제가 소프트웨어를 좋아하는 이유 중 큰 부분을 차지합니다. 통합을 구축하든, 분리된 웹 애플리케이션을 위한 API를 제작하든, 일반적으로 나와 코드 만 있으면 됩니다.

대부분의 경우 저는 1인 API 개발자로 일하고 있습니다. 솔로 활동에는 빠른 결정과 완전한 제어라는 장점이 있습니다. 하지만 모든 것을 머릿속에 저장하면 핸드오프와 위임이 까다로워지기 때문에 이는 양날의 검입니다. 그리고 혼자 진행하다 보면 제가 작업할 수 있는 프로젝트의 규모와 복잡성이 제한됩니다. 결국 나는 한 사람일 뿐이다.

Postman은 요청 전송, 환경 관리, 테스트 실행 등 API 작업을 위한 기본 도구입니다. 나는 솔로 작업 흐름에 익숙합니다. 하지만 저는 궁금해지기 시작했습니다. 팀 환경에서 Postman이 무엇을 더 제공할 수 있을까요? 어떻게 협업을 강화하고 개발 프로세스를 간소화할 수 있습니까?

이러한 질문을 탐구하기 위해 저는 "X Nihilo"라고 부르는 예제 API 작업을 시작했습니다.

API 예시: X 니힐로

X Nihilo는 저장하거나 보내는 매개변수를 기반으로 280자 트윗을 생성하는 데 도움을 줍니다. 주제, 목표, 취해야 할 어조에 대한 설명, 청중에 대한 설명을 제공합니다. API는 뒤에서 텍스트 완성을 위해 OpenAI의 API에 요청을 보내 트윗 생성을 지원합니다.

또한 톤과 청중에 사용하는 문자열을 저장한 다음 후속 트윗 요청에 재사용할 수 있습니다.

기본 API 개발 작업 흐름을 살펴보겠습니다.

혼자서 진행하기: 나의 솔로 작업 흐름

내 작업 흐름의 첫 번째 단계는 API를 설계 하고 OpenAPI 사양을 작성하는 것입니다. Postman에서 새 API를 만든 다음 새 API 정의를 시작했습니다.

몇 가지 생각을 한 후(그리고 내 설명을 기반으로 초기 OpenAPI 사양을 생성하는 데 훌륭한 ChatGPT로 직접 작업한 후) 사양을 작성했습니다.

OpenAPI 사양을 갖추면서 갈림길에 섰습니다. 이 API와 상호 작용하는 모습을 보여주기 위해 모의 서버와 몇 가지 예제 요청 및 응답을 설정해야 합니까? 아니면 구현 코드 작성을 시작해야 합니까?

개인 개발자로서 저는 언제든지 API 생산자 또는 API 소비자만 될 수 있습니다. 그래서 나는 모의 제품을 만들 필요가 없다고 결정했습니다. 내 안에 있는 소비자는 기다려야만 했습니다. 코드를 작성해 봅시다!

잠시 후…

Express와 함께 Node.js를 사용하고 PostgreSQL 데이터베이스와 통신하면서 기본 API를 구현했습니다. 다음은 제가 구축하는 데 필요한 모든 것에 대한 요약입니다.

• POST /signin username 과 password 가져와 데이터베이스의 레코드에 대해 인증한 다음 모든 후속 요청에 사용할 수 있는 서명된 JWT를 반환합니다.
• POST /generateTweet 최대 280자 트윗을 생성합니다. topic (문자열)와 goal (문자열)가 필요합니다. 또한 tone (문자열) 또는 audience ID(저장된 청중의 정수 ID)와 함께 toneId (문자열) 또는 audienceId (저장된 소리의 정수 ID)를 사용합니다. tone 및/또는 audience 문자열이 제공될 때마다 API는 이를 데이터베이스에 저장합니다.
• GET /tones 톤 ID 및 해당 문자열 목록을 반환합니다. GET /audiences 재사용 가능한 대상 문자열에 대해 동일한 작업을 수행합니다.
• DELETE /tones 톤 ID를 가져와 해당 톤 레코드를 삭제합니다. DELETE /audiences 청중 레코드에 대해서도 동일한 작업을 수행합니다.

초기 구현이 완료된 후 Postman으로 돌아가서 일부 요청 실행을 시작할 시간이었습니다.

변수를 사용하여 환경을 만듭니다.

먼저 'Test'라는 새로운 환경을 만들었습니다. 유효한 username 및 password 와 함께 root_url 저장하는 변수를 추가했습니다.

컬렉션 및 요청 만들기

그런 다음 새 컬렉션을 만들고 첫 번째 요청인 /signin 에 대한 POST 요청을 추가하여 인증을 시도했습니다.

터미널 창에서 API 서버를 실행하면서 첫 번째 요청을 보냈습니다.

성공! 향후 요청에 필요할 토큰을 받았습니다.

이번에는 트윗을 생성해 달라는 새로운 요청을 만들었습니다.

"Bearer Token"을 사용하도록 Authorization을 설정했는지 확인했고, 이전 요청에서 방금 받은 토큰을 제공했습니다.

응답은 다음과 같습니다.

효과가있다!

솔로 접근 방식 요약

그것은 내 솔로 작업 흐름에 대한 기본적인 미리보기입니다. 물론 그 과정에서 다음과 같은 몇 가지 다른 작업도 수행합니다.

• /signin 요청을 수행하는 사전 요청 스크립트를 작성한 다음 응답의 토큰을 기반으로 환경 변수를 설정합니다.
• OpenAPI 사양의 다른 모든 엔드포인트에 대한 요청을 만듭니다.
• 각 엔드포인트에 대한 테스트를 작성하여 극단적인 사례를 다루도록 하세요.

혼자 작업하는 경우 이 기본 작업 흐름을 통해 결승선에 거의 가까워질 수 있습니다. 괜찮긴 하지만 아마도 Postman에서 사용할 수 있는 기능 중 극히 일부에 불과할 것 입니다. 그리고 제가 팀으로 일한다면 Postman으로부터 더 많은 것이 필요하다는 것을 알고 있습니다.

아하 순간: 팀용 Postman을 고려하는 이유는 무엇입니까?

더 이상 X Nihilo의 단독 API 개발자가 될 수 없다면 어떻게 되나요? 이는 여러 가지 이유로 인해 발생할 수 있습니다.

• X Nihilo는 규모와 복잡성이 커지고 단일 API 개발자로는 더 이상 이를 지원할 수 없습니다.
• X Nihilo는 여러 API 개발자 또는 여러 API 팀이 참여하는 대규모 API 프로젝트 의 작은 부분일 뿐입니다.

클라이언트를 위한 모든 API 프로젝트가 내가 직접 구축할 수 있는 작은 프로젝트는 아닙니다. 때로는 API를 구축하는 팀의 일원이 되어야 할 때도 있습니다. API 팀을 이끌어야 할 수도 있습니다.

그런 일이 생기면 나는 혼자만의 사고 방식을 버리고 Postman에서 혼자 일하는 방식을 버려야 할 것입니다. 이것이 제가 Postman의 팀 관련 기능을 살펴보게 된 계기가 되었습니다.

Postman의 팀(기업) 기능 살펴보기

Postman에는 무료 계층이 있으며 일부 제한된 공동 작업 기능을 제공합니다. 이는 소규모 팀(개발자 3명 이하)인 경우 충분할 수 있습니다. Postman에는 Enterprise Essentials 계층의 일부로 추가 기능이 있습니다. 이는 전반적으로 Postman을 사용하는 대규모 조직의 API 팀에 적합합니다.

작업 공간 공유

작업공간을 사용하면 팀이 여러 API 프로젝트에서 협업할 수 있습니다. 이는 서로 다른 API를 작업하는 여러 팀이 있지만 해당 API가 서로 상호 작용하는 경우 유용합니다(일반적으로 대규모 소프트웨어 조직의 경우).

작업 공간은 실시간 협업을 구현하는 데 탁월합니다. 팀 구성원은 API 문서를 편집하고, 요청 작성 또는 테스트 작성을 위해 함께 작업하고, 전체 팀이 사용할 수 있는 모의 서버를 구축할 수 있습니다. 편집이 이루어지면 실시간으로 전체 팀과 동기화됩니다.

버전 관리

나는 솔로 API 개발자로서 내 코드의 버전 제어에 관심을 두었지만 Postman 컬렉션이나 환경의 버전 제어에는 별로 관심이 없었습니다. 내가 뭔가를 변경하면(요청 수정, 테스트 업데이트, 환경 변수 제거) 나만 영향을 받습니다. 별거 아니야.

팀으로 일할 때 상황이 언제 변하는지 확실히 알고 싶습니다. 때로는 변경 사항을 롤백해야 하는 경우도 있습니다. 다행히 Postman Enterprise를 사용하는 팀의 경우 Postman을 통해 컬렉션, 작업 공간 및 API에 대한 변경 로그에 액세스할 수 있습니다. 컬렉션을 이전 시점으로 롤백할 수 있습니다. 팀의 API 개발자로서 이것이 필요합니다. 대부분의 경우 Bob이 컬렉션을 망쳤기 때문입니다. 하지만 때로는 당신이 밥일 때도 있습니다.

역할 기반 액세스 및 사용자 구성

Postman 작업 영역의 모든 사람이 동일한 수준의 권한을 가져야 하는 것은 아닙니다. 일부 팀 구성원은 테스터이므로 요청을 보내고 테스트를 실행할 수 있는 능력만 있으면 되지만 수정할 수는 없습니다. 다른 사람들은 API 정의 수정만 허용된 디자이너일 수도 있습니다.

Postman에서는 팀 구성원에게 역할을 할당할 수 있습니다. 이는 각 팀 구성원이 팀 또는 작업 영역 내에서 갖는 액세스 종류와 권한 수준에 영향을 미칩니다.

팀은 팀 외부의 다른 사람의 액세스를 제한하는 개인 작업 공간을 가질 수도 있습니다.

또한 Postman Enterprise가 "도메인 캡처"를 지원한다는 사실도 확인했습니다. 이는 기본적으로 mycompany.biz 도메인의 모든 사용자에게 액세스 권한을 부여하여 조직의 모든 사용자를 설정할 수 있음을 의미합니다.

인라인 댓글 및 토론

Postman에는 Enterprise Essentials뿐만 아니라 모든 요금제에서 사용할 수 있는 하나의 공동 작업 기능이 있습니다. 이는 팀 구성원이 컬렉션(폴더, 요청, 예제 또는 끌어오기 요청)에 설명을 추가할 수 있는 기능입니다. Postman에서 직접 댓글을 달고 토론할 수 있다는 것은 팀 API 개발에 큰 도움이 됩니다. 팀의 API 개발 작업 대부분은 Postman에서 이루어지므로 GitHub나 다른 외부 서비스 대신 Postman에서 토론하는 것이 합리적입니다.

팀 API 개발: 승리를 위한 Postman

저는 팀에 합류할 때마다 제가 즐겨 사용하는 도구를 가져오지만 팀원들에게 그 도구를 강요하지는 않습니다. 나는 그들이 자신의 도구를 가지고 있다고 생각합니다. 그래서 각자 자신에게. 하지만 대부분의 API 개발자의 도구 벨트에는 Postman이 포함되어 있다는 느낌이 듭니다. 팀의 여러 API 개발자가 모두 단독 사고 방식으로 이러한 팀 기능 중 일부를 활용하지 않고 Postman을 개별적으로 사용한다면 부끄러운 일이 될 것입니다. Postman Enterprise 기능을 활용한다면 다음과 같은 이점을 얻을 수 있습니다.

효율성 향상

공유 작업공간에서는 공유 API 정의부터 시작합니다. 팀 구성원이 정의(또는 문서, 테스트 또는 환경)를 편집할 때마다 편집 내용이 동기화되고 모든 사람이 최신 및 최고의 정보를 갖게 됩니다.

모두가 컬렉션의 동일한 요청 세트에 대해 작업하고, 사용될 모든 테스트에 액세스할 수 있습니다. 이러한 모든 편리함은 팀의 효율성을 향상시켜 결과적으로 개발 속도를 급격하게 높일 것입니다.

오해 감소

모든 사람이 동일한 소스(작업 공간)에서 작업하고 개발에 사용하는 도구 내에서 의견을 제시하고 대화할 수 있으면 오해가 줄어들 것입니다. 귀하의 팀은 해당 엔드포인트가 쿼리 매개변수를 취해야 하는지 경로 매개변수를 취해야 하는지에 대해 혼동하느라 시간을 허비하지 않을 것입니다. 모든 것이 명확해질 것입니다.

주요 요점

저는 Postman이 팀과 기업을 위한 것인지 몰랐습니다. 이제 알고 보니 중요한 점은 다음과 같습니다. 팀 플레이어는 팀에 도움이 되는 도구를 사용합니다.

제가 혼자 API 개발자였을 때 Postman은 제게 큰 도움이 되었습니다. 다행히도 API 개발팀에 있을 때 유용하게 사용할 수 있는 기능도 있습니다. 나에게 있어서 그것은 컬렉션, 변경 로그, 버전 제어 내의 편집 내용을 실시간으로 동기화하고 액세스에 대한 세분화된 권한입니다. 이제 저는 더 큰 팀과 함께 더 큰 API 프로젝트를 맡게 되어 기쁩니다.

즐거운 코딩하세요!

여기에도 게시되었습니다.