서버 개발자에게 에러 제보 시의 매너
개발자와 대화하기
저는 가끔 외부 업체랑 커뮤니케이션을 할 때가 있습니다. 저희가 제공하는 API가 완벽할 순 없기에 가끔 이메일로 문의를 받곤 합니다. 이때 느껴본 고충을 공유해 볼까 합니다. 이것은 꼭 외부 업체에 국한된 것은 아니고요. 개발자와 소통하는 누구나에게 해당되는 이야기입니다.
잘못된 제보의 예
안녕하세요. xxxx입니다.
저희가 API를 연동하는데요. 특정 상황에 400 에러가 발생합니다.
개발 가이드 문서에 위와 같은 내용이 없어서 메일 드렸습니다.
확인 부탁드립니다. 감사합니다.
최근에 이와 같은 메일을 받았습니다. 이 걸 보시는 다른 분들은 어떻게 생각하실지 모르겠습니다만 저는 저것을 보고 아무것도 할 수 없었습니다. 심지어 서버 개발자가 저따구로저렇게 제보한다는 사실이 매우 안타깝습니다. 이것은 아래랑 비슷합니다.
안녕하세요. 손님입니다.
제가 이 백화점에서 구경을 하는데 어떤 게 하나 고장 나있었습니다.
안내를 못 찾겠어서 제보드립니다. 고쳐주세요.
과연 이것을 본 백화점 관리자는 뭘 할 수 있을까요? 백화점의 지하주차장부터 옥상까지 외관, 내관, 배수관, 전기선, 모든 기물, 모든 조명, 모든 엘리베이터, 모든 에스컬레이터 등등 모든 시설을 전수 조사해야 할까요? 현실적으로 불가능합니다.
자세한 정보를 전하자
위에 에러 제보는 뭐가 잘못된 걸까요? 잘못된 점을 찾을 필요조차 없습니다. 왜냐면 잘한 게 전혀 없기 때문입니다.
안녕하세요. 밍피디입니다.
제보해주신 내용으로는 문제를 파악하기 어렵습니다.
어떤 API를 어떤 헤더와 함께 어떤 리퀘스트 바디로 요청하셨는지 알려주시면 확인해보겠습니다.
고맙습니다.
이메일 커뮤니케이션은 실시간이 아니죠. 보통 몇 시간 혹은 며칠도 걸립니다. 저렇게 의미 없는 이메일들로 몇 시간을 까먹은 겁니다.
Rest API에 대한 제보에는 최소한 아래가 포함되어야 합니다.
API URL
→ http://mingpd.com/register 등의 URL
API Method
→ GET, POST, PUT, DELETE 등
Request Header
→ Content-Type, Accept, Authorization, 혹은 커스텀 헤더 정보
Request Body
→ POST, PUT인 경우 반드시 넣자. (JSON이 틀린 경우도 종종 있음)
Response
→ Status Code, Response Header, Response Body
호출 시각
→ 특정 시간에 배포가 있거나, 이슈가 있었을 수도 있으므로 반드시 포함.
적어도 메일에 이 정도만 넣어줬더라도 저는 제보를 확인할 수 있었을 겁니다.
CURL
위 서버 API 제보 예시에서 나열했던 필수 정보들을 말로 풀어도 서버 개발자는 확인이 가능합니다만 (오히려 저렇게라도 해주는 게 감사할 지경..) 개발자는 개발자의 언어일 때 가장 편합니다. 아래의 형태로 주는 게 가장 베스트입니다.
curl -i -X POST \
-H "Content-Type:application/json" \
-H "Authorization:인증헤더" \
-d \
'{"key": "value"}' \
'https://api.path.com/app'
이것과 함께 요청 시간과 Response까지 첨부하면 되겠습니다. 참고로 curl이란 shell에서 http 요청을 날리는 툴입니다. 우리가 브라우저에서 클릭클릭하던 것을 명령어를 통해서 요청한다고 보시면 되겠습니다.
위의 장점은, 일단 앞서 열거한 Request에 대한 모든 정보를 한 번에 표현할 수 있다는 점과 저것을 복사해서 바로 재현해볼 수 있다는 점입니다. 아무리 내가 개발했더라도 재현을 해봐야 문제점을 파악할 수 있으니까요.
만약 위 명령어를 직접 만드는 게 어렵다 싶으면 툴을 이용할 수도 있습니다.
이건 제가 사용하는 툴입니다. 여기서 리퀘스트를 생성할 수 있고 목록화하여 관리할 수도 있으며 curl 형태로 copy도 가능합니다.
이 외에도 많은 rest api 관련 툴이 있으니 궁금하신 분은 찾아보시면 됩니다.
마치며
다른 사람에게 부탁할 때 우린 매너를 지킵니다. 어떻게 말해야 할 지도 한참 고민하고, 어떤 표정을 지을지, 어떤 옷을 입을지 등도 깊게 고민하죠. 그걸 고민 안 한다고 해서 불법은 아닙니다. 하지만 그걸 받아들이는 사람의 태도는 크게 달라지겠죠.
개발자도 똑같습니다. API에 대해 문의사항이 있다면 구체적인 정보를 잘 담아주는 게 매너입니다.
