DEV Community: 김동한

생산성을 높이는 POSTMAN 기능 활용. 4편

김동한 — Wed, 12 Jan 2022 15:25:54 +0000

1편, API 인증 자동화로 API 호출을 좀 더 편하게 만들기.
2편, 콜렉션 수정내용 GIT 처럼 관리하기.
3편, API 호출 및 응답 예제를 작성해서 MOCK 서버 구축하기.
4편, 다양한 요청 포맷을 IMPORT/EXPORT.

4. 다양한 요청 포맷을 IMPORT/EXPORT.

POSTMAN은 HTTP Rest API 개발에 많은 편의를 제공하는 목적으로 사용되는 툴입니다. 그렇기에 실제 개발시에 API 호출을 편하게 실행시킬 수 있게 하기 위한 여러가지 기능들이 계속해서 추가되고 발전해오고 있습니다. 저는 백엔드 API개발 해오면서 최근 5년동안 POSTMAN을 사용해 오면서 기능들이 추가되어 가는 모습을 많이 지켜 볼 수 있었는데요. POSTMAN이 가장 초창기 부터 제공하던 기능이였으면서도 제가 너무나도 편하게 사용했던 기억 때문에 다른 툴보다 POSTMAN으로 정착하게 만들었던 기능을 오늘 소개하려고 합니다. 요청 가져오기와 내보내기 기능입니다.

요청 가져오기

먼저, 어떤 형식이든 HTTP요청에 대한 정보가 있는 형식이라면, 모두 가져오고자 하는 포부가 담긴 가져오기 기능 부터 살펴보겠습니다. 이 기능은 솔직히 블로그로 소개하는 것자체가 무의미 하지 않을까 하는 너무나도 쉽게 사용할 수 있는 기능이라서 민망하게 느껴지기도 합니다. 하지만, 의외로 주변에 가져오기 기능을 잘 사용하지 않는 분들을 생각보다 많이 보면서 알려드리면 좋을 것 같아 소개하려 합니다.

화면상에 보이듯이 현재 포스트맨이 가져올수 있는 형식은 OpenAPI, GraphQL, cURL, WDSL, HAR 이렇게 다섯가지 입니다. WDSL, HAR 형식은 최근에 추가 되었나 보네요. 백엔드 API개발을 하다보면, 기능 확인을위해 클라이언트를 직접 사용하면서, 호출이 어떻게 일어나고 응답되었는지 확인하기 위해 브라우저 개발자 도구를 사용 하게 될 때가 많이 있습니다. 대부분의 브라우저 개발자도구에서는 HTTP 요청 내역을 HAR이나 cURL 명렁으로 내보낼 수 있게 해주고 있기 때문에, 손쉽게 POSTMAN으로 가져와서 호출 테스트를 해볼 수 있게 됩니다. 웹앱에서 호출하는 API인 경우, 다음과 같이 너무 쉽게 가져올 수 있습니다.

OpenAPI 형식을 가져오는 것도 꽤 유용한데요. OpenAPI 문서 관리가 잘되어있는 개발 조직이라면, POSTMAN 요청 컬렉션으로 아주 쉽게 가져올 수 있습니다. OpenAPI문서를 가져오게 되면 POSTMAN 내에 API로 등록 되고, API를 collection 으로 만들어낼 수 있습니다. POSTMAN에서 API 레벨로 관리하면 몇가지 유용한 기능을 추가로 사용할 수 있는데 다음에 기회가 된다면 자세하게 소개하겠습니다.

요청 내보내기.

가져오기가 다양한 포맷으로 가져 올 수 있는 기능이었어서 내보내기 또한 동일 한 포맷으로 모두 내보낼 수 있을거라 생각했지만, 내보내기의 경우는 하나의 포맷으로만 가능합니다. POSTMAN에서 취급하는 collection format 으로만 내보내기가 가능합니다. 이 파일은 포스트맨에서만 사용되는 포맷이라 백업의 용도로만 사용 가능 합니다. 그리고 컬렉션 레벨에서만 내보내기가 가능합니다. 그래서인지 외부에서 다른 포맷으로 변환 해주는 기능들을 만들어서 공유하는 경우가 많이 검색되네요. OpenAPI 형식으로 변환해주는 오픈소스 툴, OpenAPI 형식으로 변환해주는 서비스

요청 단위로는 내보내기 기능이라기 보다는, HTTP 요청을 호출할 수 있는 각언어별 코드 혹은 cURL 명령문을 자동으로 만들어주는 기능이 있습니다. API에 대한 명세 정보가 있지는 않지만, 이 기능을 사용해서, 각 언어별 HTTP호출 코드를 가져다 사용 할 수도 있습니다.

생산성을 높이는 POSTMAN 기능 활용. 3편

김동한 — Wed, 10 Nov 2021 15:19:03 +0000

1편, API 인증 자동화로 API 호출을 좀 더 편하게 만들기.
2편, 콜렉션 수정내용 GIT 처럼 관리하기.
3편, API 호출 및 응답 예제를 작성해서 MOCK 서버 구축하기.
4편, 다양한 요청 포맷을 IMPORT/EXPORT.

3. API 호출 및 응답 예제를 작성해서 MOCK 서버 구축하기.

오늘은 포스트맨의 기능중에서 MOCK API서버를 손쉽게 구축하는 방법에 대해서 알아보려고 합니다.

기능개발을 하다보면, API를 사용하는 입장인 클라이언트와 동시에 개발을 진행하게 되는 상황이 자주 발생하게 됩니다. 기능 설계 단계에서 서로 어떻게 데이터를 주고 받을지에 대한 API 인터페이스 정의를 내리고 나면, 클라이언트 개발자와 백엔드 개발자는 각자 정의된 인터페이스에 맞춰서 기능 개발에 돌입합니다. 클라이언트 개발자들은 개발중에 인터페이스를 호출하는 코드를 작성하고 나면 동작 테스트를 위해, 실제 테스트를 해보아야하는데 백엔드 API개발이 완료되지 않은 상태에서는 개발 완료될 때 까지 어쩔 수 없이 기다리게 됩니다.

이런 상황을 해소헤 줄 수 있는 것이 MOCK API 서버 입니다. MOCK API 서버는 백엔드 코드를 실행하지 않고, 준비된 고정 응답을 내려보내 줄 수 있는 간단한 서버로 제공됩니다. 위 상황에서 인터페이스 정의가 완료된 상태라면, 어떤 응답이 실제로 내려가게 될지 예시를 충분히 작성 해볼 수 있고, 몇몇 예시를 만들어서 API호출시 고정된 응답으로 보내줄 수가 있게 됩니다.

포스트맨은 하나의 요청에 대해 여러 예시를 추가 할 수 있도록 기능이 마련되어 있고, 이렇게 작성해 둔 예시는 개발자가 API를 더 잘 이해 할 수 있게 만들어줍니다. 거기에 더해 포스트맨에서는 작성된 예시를 실제로 응답해 줄 수 있는 MOCK API 서버를 아주 간단하게 만들어주는 기능을 제공하고 있습니다.

예제

MOCK API 서버를 만드는 간단한 과정을 예시와 함께 보여 드리겠습니다.
아래와 같이 API 인터페이스가 정의되어 있는 상태라면 포스트맨에 컬렉션과 컬렉션내에 요청 하나를 만들 수 있습니다.

REDOC 문서

OpenAPI 3.0 정의

openapi: '3.0.2'
info:
  title: 블로그 API
  version: '1.0'
paths:
  /post/{post_id}:
    get:
      description: 블로그 상세 조회 API
      parameters:
        - in: path
          name: post_id
          required: true
          schema:
            type: number
            example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                    example: 1
                  title:
                    type: string
                    example: 첫번쨰 포스트
                  content:
                    type: string
                    example: '<p>안녕하세요 첫번쨰 <b>포스트</b> 입니다.</p>'                  
        '404':
          description: Not found

위 API 문서 YAML를 포스트맨에 임포트 시켜서 만드는 방법도 있지만 일단 여기서는 직접 만들어 낸 요청을 보여드리겠습니다.

위 화면을 보시면 Blog examples 컬렉션이 만들어진것이 보이고 Get post detail 이라는 이름의 요청을 하나 만든것을 보실 수 있습니다. 아직은 개발 된 API가 아니므로 요청을 실행해도 응답 받을 수가 없습니다.

아래 순서로 작업하여, MOCK 서버를 완성 해보겠습니다.

요청의 example을 응답 종류 만큼 생성 합니다.
API내의 모든 example 이 작성완료 되면, mock 서버를 생성합니다.
만들어진 mock 서버의 url을 host에 넣어 요청 해보고 example에 정의했던 응답이 오는지 확인합니다.

1. 요청의 example을 응답 종류 만큼 생성 합니다.

API 인터페이스 정의를 보면 API 호출시 응답 상태값 200과 404응답이 될 수 있습니다. MOCK 서버가 동일하게 200응답 404응답을 내려줄수 있도록 하려면 200과 404 각각 example을 만들어 주어야 합니다. 이때 주의 할 점은 example 에 요청 부분을 각각 다르게 지정해야, 요청에 맞게 MOCK서버가 다르게 응답할 수 있게 됩니다.

아래 예시에서는 post_id값이 1로 요청되는 경우 200 OK가 응답 되도록, post_id값이 2로 요청되는 경우는 404 Not found가 응답 되도록 example을 작성하였습니다.

200 example

404 example

2. API내의 모든 example 이 작성완료 되면, mock 서버를 생성합니다.

컬렉션 편집 메뉴 중에서 mock collection 을 선택합니다. 생성시 몇몇 설정 값을 입력하고 생성버튼을 클릭합니다.

Make mock server private 설정의 경우는 MOCK 서버에 API-KEY헤더를 넣어야 응답이 되는 수 있는 프라이빗 사용설정 입니다.
Simulate fixed network delay 설정은 MOCK서버의 네트워크 속도를 시뮬레이션 할 수 있는 옵션입니다. MOCK 서버가 응답시 특정 딜레이 경과 후 응답하게 됩니다.

3. 만들어진 MOCK 서버의 URL을 HOST에 넣어 요청 해보고 example에 정의했던 응답이 오는지 확인합니다.

post_id:1 요청시 200 응답

post_id:2 요청시 404 응답

자 이제 클라이언트 개발자분들께 인터페이스 정의가 끝나고 바로 "호출해 보실 수 있습니다." 라고 당당하게 말할 수 있게 되었습니다.

[번역] Water Cooler Chat 을 장려해야 하는 11가지 이유

김동한 — Wed, 08 Sep 2021 15:37:17 +0000

원문: Water Cooler Chat – 11 Smart Reasons to Encourage It
저자: TIM EISENHAUER

번역을 하게 된 계기.

최근 코로나로 인해, 재택근무가 장기화 되어 벌써 동료들과 떨어져 일하게 된지도 벌써 일년이 넘어 가는 것 같습니다. 재택 중에서 사무실에서 만나서 긴밀하게 일하던 모습을 기대하며 메타버스 협업 툴을 도입해서 대화의 기회를 많이 높인 부분은 재택근무의 만족도를 많이 높여주었습니다. 어느정도 만족하며 지내다 아직 뭔가 채워지지 않은 부분이 있는것 같다라는 느낌을 받던차에 이 포스트를 보고 왜 그렇게 느꼈는지 이해가 되었습니다.
사무실 안에서 일하다 보면, 커피 뽑으며 인사하고 약간의 대화를 나누거나, 간식대를 기웃거리며 짧게 인사를 나눈 다거나 하는 일이 하루에도 몇번 일어나는데, 재택 근무에서는 그런일이 일어나지 않습니다. 메타버스 협업툴을 사용하더라도 일어나지 않습니다. 커피타러 가버리면 아바타를 조종 하지 못하게 되니까요...
이런 사소해보이는 사건이 얼마나 중요했던 것 이었는지 이 포스트를 통해 알게 되었습니다.

서문

하루 근무가 끝나고 나서 오늘 완료 한 일에 해 다시 되돌아본 적이 있으신가요? 생각보다 많은 사람들이 오늘 완료한 일에 대해 되돌아보지 않고 살아갑니다.
너무 많은 사람들이 일에서 빠져나오지 못하고, 무의식적으로 일하는 자동 조종 상태로 일을 하고 있습니다. 늘상 업무 마감시간에 쫒기며, 정신없이 업무를 마무리 하며 일을 하고 있습니다.
이런 분들에게 Water Cooler Chat 이라는, 직장내 사소한 사담을 나누며 휴식하는 것이 도움이 될 수 있습니다.
Water Cooler Chat은 정수기에 물뜨러 오는 사람들끼리 마주치며, 인사나누고 개인적인 사담을 나누는 것을 뜻합니다. 개인적인 관심사를 나누거나 일과 관련없는 스트레스 받지않을 가벼운이야기를 나누며, 짧은 시간안에 리프레시 할 수 있는 기회입니다.
Water Cooler Chat은 정수기가 발명 되기 전부터 일어나던 일이며, 정수기 주변에서 흔히 발견되기에 해당 명칭을 얻게 되었습니다. 하지만 불행하게도 Water Cooler Chat을 하는 사람들은 주변 사람들에게 나쁜 평판을 얻기 쉽습니다. 어떤 관리자들을 Water Cooler Chat이 생산성을 저해한다고 생각 하기도 합니다. 허용한다고 하더라도 개인적으로 주어지는 휴식 시간을 대신 줄이라고 말하기도 합니다.
Water Cooler Chat은 어떤 사람이든 언젠가는 필요한 활동 중에 하나임을 주장하려합니다. 사람은 기계가 아닌 인간으로, Water Cooler Chat을 통해 휴식을 취하고 회사 생황을 즐길 수 있게 하며, 구성원의 유대를 증가 시킬 수 있습니다. 관리자들에게도 회사가 성장하고 직원들의 소속감을 높일 수 있는 방법임을 알려주고자 합니다.

11가지 이유

1.기업 문화를 구축합니다.

기업 문화는 중요성은 나날이 높아지고 있습니다. 어떤 직원에게는 기업 문화가 급여와 승진보다 더 강력한 동기 부여가 됩니다. 기업 문화는 본질적으로 공통의 목표 혹은 더 높은 가치를 위해 일하는 사람들을 결속시킵니다. 관심을 갖고 갖춰 나갈수록 회사의 잠재력이 커집니다.

적극적인 직원 참여 없이는 회사가 변영 하기 힘듭니다. Water Cooler Chat이 문화 형성에 많은 도움을 줄 수 있습니다. 일하며 배우고, 성장하는 즐거움을 나눌 수 있도록 장려하여 문화로서 정착시키세요. Water Cooler Chat은 개인적인 차원에서의 화합을 통해 문화를 향상 시킵니다.

2. 사람들을 방어적인 태도에서 벗어나게 도와줍니다.

사회적 불안감은 대부분의 직장인들에게 실제로 존재 합니다. 사회적 불안감으로 고통 받는 사람들은 다른 사람들과 마음을 열고 대화하는데 어려움을 겪을 수 있습니다. 이로인해 의사 소통에 장애가 생겨, 원할한 협업을 하기 어려운 사람들도 있습니다. 사회적 불안감을 완전히 치료 할 수는 없을 테지만, 스스로가 방어적인 태도를 벗어날 수 있도록 분위기를 부드럽게 만들어 줍니다. 불안감을 느끼는 분들을 Water Cooler Chat에 참여하게 하세요. 스스로가 사회적 불안을 해소 하고 싶다고 도전하는 분들에게 중요한 시작점이 될 수 있습니다.

3. `Water Cooler Chat`으로 리텐션이 향상됩니다.

사람들은 일하는 곳이 안정감을 주지 못할때 직장을 떠나게 됩니다. Water Cooler Chat은 작은 활동 이지만 편안함, 지지감, 리텐션을 구축할 수있는 강력한 수단입니다.
관리자들은 이직율이 높은것을 원하지 않습니다. 신규 입사자를 고용하는것이 직원의 이직을 막는것보다 발생하는 비용이 훨신 높습니다. 직원의 만족도를 항상 민감하게 생각하고 만족도를 높일 수있는 죄상의 환경을 제공하기 위해 노력해야 합니다.

4. 관리자와의 캐쥬얼한 대면시간을 가질수 있게 해줍니다.

직원이 관리자와 대화하는 것을 두려워하거나 주저하면 비즈니스가 어려움을 겪을 수 있습니다. 이는 비즈니스 세계에서 일반적인 현상입니다. Water Cooler Chat은 개인 수준에서 모든 사람을 연결할 수 있기 떄문에 팀 구성원과 경영진 사이의 장벽을 허물게 해주는데 좋은 역할을 합니다. 사람들은 이와 같은 상황에서 마음을 열고 문제를 해결하는 데 편안함을 느낄 가능성이 더 큽니다. Water Cooler Chat은 사람들이 관리자와 더 편안하게 지내낼 수 있게 해주는 이상적인 활동입니다.

5. 협업 능력이 높아집니다.

직원들이 프로젝트에서 성공적으로 협력하기 위해서는 상호 신뢰와 존중이 있어야 합니다. 상호간 협업을 주저하지 않고 쉽게 시작 할 수 있도록 만들어주는 것은 개인적인 레벨의 높은 유대감입니다. 휴식을 취하고 업무와 관련되지 않은 주제에 대해 토론할 수 있도록 하면 이러한 관계를 개선하는 데 도움이 될 수 있으며, 서로 편안하게 협업하고 놀라운 일을 할 수 있습니다.
복잡한 작업을 함께 하기 전에 누군가를 알아가는 것은 큰 차이를 만들 수 있습니다. 구조화된 미팅 대신 직원들이 쉬는 시간에 서로를 알아가도록 격려하십시오. 그들이 개인적인 관계를 구축함에 따라 프로젝트 협업 이 훨씬 쉬워집니다.

6. 생산성이 높아집니다

당연한 이야기 지만, 리더는 직장 생산성을 개선할 방법을 항상 찾고 있습니다. 어떤 사람들은 사무실에서 잡담을 하는 것이 사람들이 헛소리를 하고 있다는 것을 의미한다고 생각하지만 이는 잘못된 생각입니다. 직원들이 스트레스를 풀고 일에서 물러나기 위해 종종 서로 대화해야 합니다. 그래야 작업을 하기 위해 돌아올 때, 새로운 사고방식을 갖고 더 많은 업무를 처리 할 수 있게 됩니다.

7. 건강한 상태의 직원들이 많아집니다.

현대의 전문가들은 직장에서의 긴장과 스트레스에 익숙하지 않습니다. 비즈니스가 확장되고 더 성공적으로 성장함에 따라 더 큰 문제로 번질 수 있습니다. 긴장은 유독하기에 생산성을 낮추고, 워크플로를 망치며, 높은 성과의 직원들 까지도 번아웃 시킬 수 있습니다.
직원들이 긴장을 풀고 자신의 취미와 관심사에 대해 이야기할 수 있는 기회가 있을 때(마감 시간에 맞춰 일하는 대신에) 스트레스가 풀리기 시작합니다.
많은 관리자와 CEO는 직원을 건강하게 유지하는 것의 중요성을 간과합니다. 건강한 직원은 정시에 출근하고, 사려 깊은 마음가짐을 유지 하며, 회사를 성장시킵니다. 스트레스는 정신적, 육체적 건강에 막대한 영향을 미칠 수 있으며, 업무 중 휴식을 취하는 시간을 갖는 것이 중요합니다. 실제 사무실 환경에서 Water Cooler Chat은 사람들이 일어나서 움직이도록 강요하는데, 이는 결코 나쁜 일이 아닙니다.

8. 좋은 아이디어와 솔루션을 떠올리는데 도움을 줍니다.

훌륭한 아이디어를 떠올리는 데는 많은 생각을 떠올릴 필요가 있으며 토론을 위한 플랫폼을 제공하는 것이 아이디어 발견 까지의 속도를 높이는 데 도움이 됩니다. 사람들이 문제에 대해 끊임없이 이야기 해야만 훌륭한 아이디어와 솔루션이 나오지 않는다는 것을 의미하지는 않습니다.

직원들이 업무나 문제와 관련없는 스포츠나 TV에 대해 이야기하고 있겠지만, 이러한 다른 관점의 정기적인 대화가 좋은 아이디어를 도출 해내기 위한 영감을 제공 할 수도 있습니다. 간간히는 정수기 대화에서 나온 아이디어가 직접적으로 새로운 제품과 서비스에 영향을 줄 수도 있습니다. 브레인스토밍과 문제 해결을 위한 캐주얼한 방법으로 생각하면 됩니다. 이러한 사실은 직원들이 Water Cooler Chat에 참여하면서 회사에 기여할 수 있음을 의미합니다.

9. 원격 직원의 참여도를 높입니다.

원격직원의 경우, 더욱이 동료들과 대면 할 수 있는 기회가 적습니다. 가상의 Water Cooler Chat에 참여 하게 하여 참여도를 높일 수 있습니다.

10. 직원 몰입도를 높입니다.

직원 참여는 산업에 관계없이 비즈니스의 성과에 큰 영향을 주는 핵심 적인 요소입니다. 직원 몰입도를 높이는 일은 리더십 위치에 있는 모든 사람에게 최우선 순위가 되어야 합니다.
직원들에게 동료들과 긴장을 풀 수 있는 시간을 주어야 합니다. 이러한 유형의 동료애는 직원 간의 우정과 신뢰를 구축하는 데 도움이 될 것이며 궁극적으로 직장의 사기와 참여 수준을 향상시킬 것입니다.
참여 수준이 저하되면 모든 것이 무너집니다. 낮은 참여도는 모든 회사에 해롭지만 일반적으로 발생하는 문제입니다. 다행히도 Water Cooler Chat은 업무에 적용할 수 있는 쉬운 요소입니다. 직원들이 휴식을 취하고 정수기 주변에서 대화할 수 있도록 하면 참여도를 높일 수 있습니다.

11. 편안한 `Water Cooler Chat`정책이 있다면, 경영진에 대한 존중을 이끌어낼 수 있습니다.

직원 관리는 쉽지 않습니다. 직원들이 좋은 일을 하도록 만드는 가장 좋은 방법은 관리자가 직원들의 존경을 받고 관리자는 그들을 신뢰한다는 것을 보여주는 것입니다. 대부분의 사람들은 스트레스를 받지 않는 작업 환경을 찾고 있으므로 이를 제공하면 많은 추가 점수를 얻을 수 있습니다. 관리자가 경찰이 되지 않겠다고 분명하게 이해시킨다면, 존경심이 더 강해집니다.

마무리

이번 포스트에서는 11가지 이유까지만 번역하고, 이후에 Water Cooler Chat을 어떻게 하면 좋은지 DO AND DONT 에 대해서 이어 번역 하도록 하겠습니다. 장점은 극대화 하고, 단점을 크게 만들지 않도록 하는 방법을 설명 하게 될 것 입니다.

생산성을 높이는 POSTMAN 기능 활용. 2편

김동한 — Wed, 14 Jul 2021 15:17:59 +0000

1편, API 인증 자동화로 API 호출을 좀 더 편하게 만들기.
2편, 콜렉션 수정내용 GIT 처럼 관리하기.
3편, API 호출 및 응답 예제를 작성해서 MOCK 서버 구축하기.
4편, 다양한 요청 포맷을 IMPORT/EXPORT.

2. 콜렉션 수정내용 GIT 처럼 관리하기.

1편에서, 포스트맨에서 Request를 묶는 최상위 단위는 Collection 이라고 말씀드렸었는데, 포스트맨은 Collection 이라는 단위를 다양하게 관리 활용 할 수 있도록 여러 기능을 제공하고 있습니다.

오늘은 여러 기능중에서도 Collection을 다른 사람과 공유하는 share 기능에 대해서 좀 더 상세 하게 알아보고, share 상황에서 어떻게 Collection을 공동 작업 할 수 있는지를 알아보겠습니다.

Collection share

본인이 작성한 Collection을 다른 사람에게 공유 할 수 있는 기능으로, 공유대상은 주로 Workspace 가 됩니다. 따라서, 해당 Workspace에 접근 가능한 사용자들은 공유된 Collection에 접근이 가능하고, Collection내에 존재 하는 Request를 실행 시켜 볼 수 있습니다. Collection 작성자는 손쉽게 다른 사람에게 공유할 수 있으니 자주 사용되는 기능중에 하나 입니다.

아래 방법을 통해 공유 할 수 있습니다.

공유하고자 하는 Collection을 선택하여 share 메뉴로 진입.
share 할 대상 workspace 선택.
share 이후에 원본 Collection을 삭제 할것인지 | 그대로 둘것인지 선택.
share 될 Collection에 접근 가능한 사용자의 권한 설정.

Collection 공유 이후 작성자만 수정 업데이트를 하거나, 앞으로 수정 될 일이 아예 없다면 share기능으로 충분하지만, share이후에 Collection을 공유받은 다른 사람이 Collection을 수정 해야하는 상황이 오면, share만으로는 충분 하지 않을 수 있습니다.

Collection은 share 상태에서 어떤 워크스페이스에서 수정이 일어나건 저장을 하는 순간 모든 워크스페이스에 바로 적용이 됩니다. 이러한 사항 때문에 동시에 Collection을 여러 사용자가 사용하고 있는 상황이라면, 누구한명이 저장을 하는순간 다른 사용자는 영문도 모른채 수정된 Collection을 사용할 수 밖에 없습니다. 이를 위해 공동 작업에 용이한 Collection fork 기능을 포스트맨에서 제공하고 있습니다.

Collection fork

개발자들에게는 익숙한 용어인 fork 가 등장 했습니다. github에서도 자주 언급되고, OS의 process를 다룰 때도 언급이 되는 용어로, 복제하여 분기된 것이라는 의미로 자주 사용되는 용어입니다.
포스트맨에서도 fork 용어는 동일한 의미로 사용 되고 있습니다. Collection 을 fork 하면, 원본 Collection을 복제한 새로운 Collection을 생성하게 되고, fork된 Collection 가지고 자유롭게 수정을 할 수 있습니다. 이뿐이라면, Collection을 복사하는것과 다를바가 없는 기능이지만, fork된 Collection은 fork된 이후의 수정사항을 언제든 원본 Collection에 수정 내역만을 업데이트 시킬 수 있다는 것이 다릅니다.
위와같은 동작 덕분에, 여러사람들에게 공유된 Collection을 공동 수정 할 수 있게됩니다. 아래와 같은 예시 상황에서 fork 는 수정사항의 충돌을 해결 해줄 수 있습니다.

예시 상황

개발자 A,B는 공유된 동일한 Collection인 payment Collection에 존재하는 결제 조회 Request를 수정 하려 함.
A의 수정 내용: 결제 조회 Request의 extension이라는 query parameter를 삭제 함.
B의 수정 내용: 결제 조회 Request의 extension이라는 query parameter의 value값을 true 함.

share 상태에서의 결과.

share 상태라면 A,B가 저장한 시간순에 영향을 받습니다. A가 먼저 저장하고 B가 저장 했다면, A는 삭제 했음에도 extension query parameter가 다시 부활한 것으로 보여집니다.

fork 상태에서의 결과

A,B가 payment Collection을 각자 fork하여 payment-A, payment-B Collection 에서 수정 하고 저장한 뒤 원본 Collection인 payment에 수정 사항을 반영 하기 위해 각자 pull request 를 만듭니다.
payment-A의 pull request를 merge 하고, payment-B pull request를 merge 하려고 하면 conflict이 발생 했기 때문에 conflict를 해결하라는 알림이 뜨고, payment-B pull request는 거부 처리 합니다.
이렇게 되면, A의 수정 사항만 원본에 반영 되고 충돌은 해결 됩니다.

결론

공동 수정이 많은 컬렉션은 fork를 이용하여 수정 관리하자.
수정이 일어나지 않거나, 1명이 수정한다면 share를 이용하자

생산성을 높이는 POSTMAN 기능 활용. 1편

김동한 — Wed, 23 Jun 2021 15:01:08 +0000

1편, API 인증 자동화로 API 호출을 좀 더 편하게 만들기.
2편, 콜렉션 수정내용 GIT 처럼 관리하기.
3편, API 호출 및 응답 예제를 작성해서 MOCK 서버 구축하기.
4편, 다양한 요청 포맷을 IMPORT/EXPORT.

1. API 인증 자동화로 API 호출을 좀 더 편하게 만들기.

API 호출 테스트를 하려면 일반적으로 인증 토큰 혹은, 인증에 필요한 값을 서버로 부터 받아 API 호출시 값을 전달하여 인증 하게 됩니다. 이러한 일반적인 API 호출 환경을 지원하기 위해, POSTMAN에서는 Authorization 기능을 제공 하고 있습니다.

첫번째로 Authorization 기능을 활용한 API인증 셋팅 방법을 소개 하고, 약간은 아쉬운 듯한 Authorization 기능을 대체 할수 있도록 설정하는 방법까지 소개 하겠습니다.

포스트맨은 collection이라는 API의 최상위 묶음 단위가 있고, 하위 계층으로 folder 묶음이 있고, 하위에 request가 포함되는 구조로 여러 request를 묶어서 관리 할 수 있습니다.

각 묶음단위 별로 Authorization을 설정 할 수 있는데, 인증 방식이 보통 API 전체적으로 적용되기에 collection 단위로 셋팅 하는 예를 보여드리겠습니다. 가장 간단한 API key 타입 인증의 셋팅 예시입니다.
API 제공자로부터 특정 HTTP 헤더 값에 제공한 KEY값을 넣어서 요청할 것을 가이드 받았다면, API key Type으로 Authorization을 셋팅 하면 됩니다.

collection의 Authorization 탭으로 이동합니다
Type 에서 API key를 선택합니다.
특정 헤더 값의 이름을 key항목에 입력 합니다. 제공받은 key값은 value항목에 입력합니다.
Add to 항목은 Header로 선택합니다.

이렇게 셋팅 하면 collection내의 모든 API 요청시 셋팅한 헤더가 추가되어 요청됩니다.

하지만! API key 타입의 셋팅으로는 어려운 상황이 발생하기도 합니다. 인증 값이 수시로 변경 되고 유효기간을 지니는 경우(JWT 같은)는 Authorization기능으로 셋팅하기가 힘든 경우인데요. 이 경우, 토큰을 발급 받기위해 하는 작업을 매번 반복 해야하는 불편함이 있습니다.

이 불편함을 해소 할 수 있는 자동화 설정 방법을 소개합니다. Pre-request script 기능을 활용한 토큰발급 자동화 방법입니다. Pre-request script
기능은 간단하게 설명하자면, 요청을 보내기전에 Javascript 코드를 실행 시켜주는 기능 입니다. Pre-request script 또한 Authorization기능처럼 모든 묶음 단위에 설정이 가능 합니다. 마찬가지로 collection에 셋팅하는 예시를 보여 드리겠습니다.

collection의 Pre-request script 탭으로 이동합니다.
실행시킨 코드를 작성 하면, 셋팅 완료 됩니다.

스크린샷에서 입력된 아래 Javascript 코드도 아래에 공유드립니다. 아임포트 API(API 문서)의 토큰을 얻어오는 스크립트입니다. 스크립트에서 하는 동작은 간단합니다. 토큰을 얻어오는 API를 http 요청하여 응답을 받고, 응답된 토큰 값을 실제 요청될 요청 객체에 헤더값으로 셋팅하는것이 전부입니다.



pm.sendRequest({
    url: 'https://api.iamport.kr/users/getToken',
    method: 'POST',
    header: {
    'Accept': 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: {
        mode: 'urlencoded',
        urlencoded: [
        {
            key: "imp_key", 
            value: "xxxxxxxxx", 
            disabled: false
        },
        {
            key: "imp_secret", 
            value: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 
            disabled: false
        },
    ]
    }
}, function (err, res) {
    res_data = res.json()
    console.log(res_data)
    pm.request.headers.add({
        key: "X-ImpTokenHeader",
        value: res_data.response.access_token
    });
});

여기서 자세하게 알아야 할 부분은 pm¹이라는 객체인데, 포스트맨에서 Pre-request script가 동작 하기전에 미리 준비해놓는 객체입니다. pm이라는 객체 내에 여러 메서드들과 멤버가 존재하는데 여기서는 sendRequest() 메서드와 request 객체를 사용했습니다.
우선, sendRequest()를 사용해서 users/getToken API를 호출합니다. 이때, 아임포트에서 제공받은 imp_key값과 imp_secret값을 body 담아 요청 합니다.
API 호출 응답이 오면, 응답 callback이 호출 되고, pm.request.headers.add()를 호출하여, 실제로 보내질 요청의 헤더에 X-ImpTokenHeader헤더를 추가하고 스크립트는 종료됩니다. 스크립트가 실행된 이후에, 호출하려고 했던 API가 호출 되며, 아래와 같이 인증을 통과한 정상적인 결과값을 확인 할 수 있게 됩니다.

스크립트에 console.log(res_data)를 넣어두면 위 스크린샷 처럼 console 창에서 메세지를 확인 할 수 있습니다. token값이 잘 응답 되었고, 요청헤더에도 잘 추가된 것을 확인 하실 수 있습니다.

위 예시코드에서는 토큰 만료까지 토큰을 재사용 하지 않고, 무조건 요청전에 토큰을 가져오게 됩니다. users/getToken API결과 값 중의 expired_at값을 활용하여, 만료전까지 토큰을 재사용하는 코드로 개선을 할 수도 있을 것으로 보입니다.

pm객체 에 대한 document를 확인하고 사용하자. ↩

좋은 소프트웨어 설계 문서를 작성하는 방법.

김동한 — Wed, 14 Apr 2021 16:01:01 +0000

해당 포스트는 how-to-write-a-good-software-design-document의 한글 번역 포스트입니다.

저는 소프트웨어 엔지니어로서, 어떤 형태의 문서든 설계문서를 읽거나 쓰는데에 많은 시간을 보냅니다. 지금까지 저는, 성공적인 소프트웨어 개발 프로젝트와 좋은 디자인 문서는 강한 상관관계가 있다는 결과를 많이 목격 해왔습니다.

이 포스트는, 어떤 요소들이 좋은 설계문서를 만드는지 에 대해 설명 하려고 작성하였습니다.

총, 4개의 섹션으로 나누어져 있습니다.

설계 문서를 작성하는 이유.
어떤 내용이 설계문서에 포함되는지.
작성 방법.
관련된 프로세스.

1. 설계문서는 왜 만드나요?

설계문서(aka.테크니컬 스펙)는 문제 해결 방법/계획에 대해 설명하는 문서입니다.

코드를 작성하기 전에 디자인 문서를 작성하는 것이 왜 중요한지에 대한 포스트는 이미 많이 존재합니다. 이외에, 제가 이 포스트에서 이야기 하려고 하는 것을 한 문장으로 정리하자면 아래와 같습니다.

설계문서는 올바른 작업을 수행하는데 있어 가장 유용한 도구이다.

설계 문서의 주요 목표는 디자인에 대해 문서로 작성 할 수 있는 수준으로 작성자가 고민하게 강제하는 것과 다른 사람으로 부터 피드백을 수집하여, 좀 더 완성도 높은 개발 결과물을 만들 수 있게 하는 것입니다. 일반적으로 대부분의 사람들은 다른사람들에게 시스템에 대해 알려주기 용이하기 때문에, 기록으로 남김으로써 나중에 다시 찾아보기 위해 필요하기 때문에 설계문서를 작성 해야한다고 생각하지만, 이는 주요 목표가 아닙니다.

일반적으로, 엔지니어가 1 개월 이상 소요될수 있는 프로젝트를 작업하는 경우 설계문서를 작성 해야합니다. 그렇다고 해서 작은 작업일 때 필요 없다는 말은 아닙니다. 작은 규모의 작업시에도 설계문서 작성의 이점을 충분히 누릴 수 있습니다.

좋습니다 좋아요! 여기까지 이 포스트를 읽고 계신다면, 디자인 문서의 중요성에 대해서 믿음을 갖고 계신 분이시네요. 실제 설계문서를 접해보신 분들 이시라면, 다양한 형태의 설계문서를 보셨을 것 같습니다. 아래에서는 다양한 형태의 설계문서 속에서도 좋은 내용, 스타일, 프로세스가 무엇인지 설명하려 합니다.

2. 설계문서에는 어떤 내용이 있어야 하나요?

위에서도 언급 하였듯이 설계문서는 문제에 대한 솔루션을 설명합니다. 해결하려는 문제의 성격에 따라 설계문서의 구조를 다르게 구성하는 것이 좋습니다.

최소한 포함 되어야 할 항목은 아래와 같습니다.

제목과 사람

디자인 문서의 제목.
작성자. (작업을 담당한 사람과 동일 해야 함)
문서 검토자. (프로세스 섹션에서 자세하게 설명 됨)
최신 업데이트 날짜.

개요

다른 엔지니어들이 문서의 나머지 부분을 이어서 읽어야 할지 결정 하기 위해, 높은 수준으로 요약 되어야합니다. 최대 3개 문단으로 구성 되는것이 권장됩니다.

문맥

직면한 문제가 무엇인지에 대한 설명.
이 작업이 필요한 이유.
이 작업 내용을 평가하기 위해 알아야할 사항
이 작업이 만족시키는 기술 전략.
팀의 목표에 어떻게 부합하는지.

목표

사용자(엔지니어 일 수도 있음) 관점에서의 결과물의 가치
성공 여부를 측정 하는 방법에 대한 설명.

목표가 아닌 것

이 작업으로 수정하지 않을 문제를 설명 하는 것도 매우 중요합니다.

마일스톤

PM과 관리자가 마일스톤의 내용을 확인하고, 대략적인 완료일을 알 수 있도록 체크포인트를 명시하여 작성합니다. 작업의 크기가 1개월 이상인경우 주요 사용자 별 마일스톤으로 나누어 작성하는것이 좋습니다.

날짜를 사용 하여 표현 함으로써, 휴가, 회의 일정 과는 관계없이 작성하는 것이 좋습니다.

시작 일자 : 2018. 7. 7.

마일스톤1 — MVP 기능 개발 완료: 2018. 6. 28.

마일스톤2 - 기존 시스템 중단: 2018. 7. 30.

완료 일자 - 신규 시스템에 기능 추가: 2018. 8. 10.

이러한 마일스톤 중 일부의 ETA가 변경되는 경우, 변경된 마일스톤에 대해 하위 섹션[Update]을 추가하면 이해 관계자가 최신 추정치를 쉽게 볼 수 있습니다.

기존 솔루션 (신규기능 추가가 아닌 경우)

현재 구현된 사항을 설명합니다. 사용자가 시스템과 인터렉션 하는 방법과 인터렉션 시에 데이터가 변경 되는 흐름을 설명 해야 합니다. 이해를 돕기 위해, 충분한 예제를 포함하는 것이 좋습니다.

유저 스토리는 이를 위한, 좋은 프레임입니다.

제안하려는 솔루션

가장 중요한 내용입니다. 어떻게 문제를 해결 할 수 있는지가 모두 설명 되어야 합니다. 이 또한 사용자스토리 프레임으로 설명 되면 좋습니다. 많은 하위 섹션들과 다이어그램을 포함 하여 이해를 높여야 합니다.

큰그림을 가장먼저 제시 하세요. 작성자가 휴가를 가더라도 이 섹션을 다른 엔지니어가 보고 그대로 구현 할 수 있도록 작성하세요.

대체 솔루션

위의 솔루션을 대체 할 다른 대안이 있다면 무엇이 있는지 간단하게 나열 해봅니다. 오픈소스를 사용한다거나 구매 할 수 있는 솔루션을 고려 할 수도 있습니다.

테스트 가능성, 모니터링 및 경고

개인적으로 이 섹션이 포함 되는것을 추천합니다. 읽는 사람들이 이 내용이 없을 때는 보통 해당내용에 대한 생각을 먼저 떠올리지 않습니다. 사람들은 운영 중에 문제가 발생했을 때 이문서로 다시 돌아와서는 신나게 까내리게 됩니다. 빌미를 제공하지 않도록 미리 방어 합시다.

다른 팀에 영향을 주는 부분

dev-ops팀에 어떤 영향을 주나요?
해당 솔루션이 발생시키는 추가 비용은 얼마인가요?
보안 취약점이 노출되나요?
부작용은 어떤 것이 있을수 있나요?
서비스 운영팀이 해당 개발사항을 고객에게 어떻게 전달해야하나요?

열린 질문

확실 하지 않은 미해결 사항, 독자가 고민 해줬으면 하는 부분, 논의가 필요한 사항들을 적습니다.

상세 타임라인

해당 섹션은 프로젝트에서 작업하는 엔지니어, 기술 책임자, 기술 관리자에게 알리는 내용 입니다. 보통 문서의 마지막에 위치합니다.

3. 작성 방법

1번 섹션 에서는 좋은 설계문서에는 어떤 내용이 담기는지에 대해 알아 보았고, 이제는 스타일에 대해 이야기 하려합니다. 고등학교의 영작 수업과는 다를 것을 약속합니다.

가능한 간단하게!

학술 논문처럼 작성하려 하면 안됩니다. 학술 논문은 논문 심사관에게 깊은 인상을 주기 위해 작성합니다. 설계문서는 솔루션을 팀원들에게 이해시키고, 피드백을 받기 위해 작성됨을 잊지 말아야합니다. 다음 문장 스타일링으로 내용의 명확성을 높일 수 있습니다.

간단한 단어.
짧은 문장.
불릿 목록/번호 목록.
구체적인 예제.

많은 차트와 다이어그램!

차트는 여러 잠재적 옵션을 비교하는 데 유용 할 수 있으며, 일반적으로 다이어그램은 텍스트보다 구문 분석하기 쉽습니다. 다이어그램 작성에는 구글 드로잉 앱이 최고였습니다.

PRO TIP: 다이어그램 이미지 아래에 편집 가능한 다이어그램 링크를 같이 첨부 합니다. 그래야 다이어그램 변경시 업데이트가 쉽습니다.

숫자 포함

검토자가 상태를 파악할 수 있도록 DB 행 수, 사용자 오류 수, 지연 시간과 같은 실제 숫자, 사용량에 따라 늘어나는 시간 복잡도(Big-O)를 넣어 표현 하세요.

웃기려는 노력

다시한번 말하지만 학술 논문이 아닙니다. 독자가 읽을 때 집중력을 높일 수 있도록 하는 좋은 스타일링 입니다. 문제 핵심을 벗어나게 할정도로 과도하게 사용하는 것은 금물입니다.

저처럼 재미없게 작성하는 사람들을 위해 조엘은 이런 팁을 제안 했습니다.

재미있게 작성하는 가장 쉬운 방법은, 예시를 작성할때 "사용자가..." 대신 "왼손잡이 아보카도 농부가..." 와 같이 쓸데없는 주변 정보를 넣는 것 입니다.

읽으면서 상상력을 불러 일으 키도록 합니다.

리뷰어 빙의 테스트

다른 사람에게 문서 리뷰 요청하기전에 본인이 리뷰어로 빙의 하여 한번 검토해보세요. 발견되는 문제들이 있을 수 있습니다.

휴가 테스트

지금 이 문서를 작성하고 휴가를 떠나더라도 팀원이 문서를 읽고 의도 한대로 구현 할 수 있나요? 이 테스트를 통과 해야합니다.

4. 프로세스

네 이제 대망의 마지막 단원인 프로세스 입니다. 설계문서는 잘못된 솔루션에 대한 구현을 진행하기 전 피드백을 받는데 도움이 됩니다. 좋은 피드백을 받는 방법에 대해서는 이후 포스트에서 작성 하겠습니다. 지금은 작성 프로세스와 피드백 프로세스에 대해 구체적인 설명을 하도록 하겠습니다.

첫째, 모든 작업 참여자는 설계 프로세스에 모두 참여해야 합니다. 모든 작업 참여자들이 토론에 참여하고 설계 내용에 대해 동의 해야합니다.

둘째, 설계 프로세스의 시작인 아이데이션은 단순히 노트에 아이디어를 끄적이는 것으로 는 충분하지 않습니다. 직접 솔루션의 프로토타입을 만들어 보세요. 솔루션의 구현용
코드를 작성 하는것이 아닙니다. 아이디어의 유효성을 검사하기 위한 목적으로 일회성 코드를 작성하고 실행시켜 유효성을 검증 합니다. 해당 프로토 타입코드가 develop/master 브랜치에 머지되지 않도록 규칙을 만들 필요가 있습니다.

이후, 솔루션의 실마리를 찾았다면 아래를 수행 하면됩니다.

숙련된 엔지니어 혹은 기술 책임자에게 리뷰어가 되도록 미리 요청 해둡니다. 문제에 대한 인지가 되어있는 사람들이 좋습니다. 버블티를 뇌물로 주고 매수합니다.
화이트 보드가 있는 회의실로 이동합니다
매수한 엔지니어에게 문제를 설명하세요.
생각하고 있는 솔루션을 설명하고 설득해 봅니다.

디자인 문서를 작성하기전에 위 작업을 수행하면, 문서작성에 더 많은 시간이 투자되기전에 피드백을 더빠르게 받을 수 있습니다. 솔루션이 동일하게 유지 되더라도 리뷰어는 다루어야 할 코너 케이스를 지적하고, 나중에 발생할 수있는 어려움을 예상 할 수 있습니다.

그런 다음, 설계문서의 초안을 작성하고 위 검토자가 다시 읽어보게 합니다. 그리고 제목및사람 섹션에 리뷰어를 추가 해 놓습니다. 이는 리뷰어에게 책임을 부여 합니다.

작성자와 리뷰어가 승인한 후, 피드백 및 지식 공유를 위해 팀 구성원 전체에 공유합니다. 검토 지연을 방지하기 위해 검토 일정을 1주로 제한 하는 것이 좋습니다. 사람들이 1주내에 남기는 모든 질문과 의견을 다룰 것을 같이 약속 합니다.

마지막으로, 피드백 주간에 있었던 논쟁이 있다면, 논쟁의 요점을 토론 섹션에 추가합니다. 이후, 논쟁에 참여했던 사람들과 회의를 설정 하여, 집중적인 논쟁을 하고 결론을 도출합니다.

토론 스레드의 댓글 길이가 5개 이상일때 회의를 통한 논쟁으로 이동하는 것이 효율적입니다. 모든 사람들이 동의 할 수 없는 상황이더라도 최종 결정은 작성자가 합니다.

이에 대해 최근 Shrey Banga 와 대화 하면서 Quip이 유사한 프로세스를 가지고 있다는 것을 알게되었습니다. 단, 숙련 된 엔지니어 또는 기술 책임자가 팀에 리뷰어인 것 외에도 다른 팀 의 엔지니어 가 문서를 검토하도록 제안 합니다. 실행 해본적은 없지만, 이것이 다른 관점을 가진 사람들로부터 피드백을 얻고 문서의 일반적인 가독성을 향상시키는 데 도움이되는 것을 확실히 볼 수 있습니다.

위의 모든 작업을 완료 했으면 구현을 시작할 시간입니다! 설계 사항을 구현할때 이 디자인 문서를 살아있는 문서로 취급하세요. 원래 솔루션을 변경하거나 범위를 업데이트하는 데 도움이되는 내용을 배울 때마다 문서를 업데이트 하세요.

마지막으로, 디자인 문서의 성공 여부를 어떻게 평가할까요?

Kent Rakip 이 이에 대한 좋은 답변을 준비해주었습니다. ROI가 충족되면 설계 문서는 성공적입니다. 성공적인 디자인 문서는 다음과 같은 결과를 도출 할 수도 있습니다.

디자인 문서를 작성하는 데 5 일이 소요되므로 기술 아키텍처의 여러 부분을 생각해야합니다.
리뷰어로부터, 제안된 아키텍처에서 가장 위험한 부분인 X에 대해 피드백을 받습니다.
프로젝트의 위험을 줄이기 위해 X에 대해 제일 먼저 구현하기로 결정했습니다.
3 일후, X가 불가능 하거나 원래 의도했던 것보다 훨씬 더 어렵다는 것을 알게됩니다.
프로젝트에 대한 작업을 중단하고 대신 다른 작업에 우선 순위를 부여하기로 결정했습니다.

위 결과 또한 디자인 문서의 목표인 올바른 작업을 수행하는 것을 만족 시킨 결과 입니다. 설계문서 덕분에 이 프로젝트를 실행하기 위해 1달을 낭비하는 대신 8일만 소비하고 종료 되었습니다. 성공적이라는 판단을 할 수 있습니다.