문서 똑바로 쓰자!

💡 이 글은 엄격한 문서 작성법을 강요(?)하는 내용이 아닌, 엉뚱한 API 문서 때문에 수 일을 날린 학생 개발자의 한풀이 & 나름의 느낀 점을 공유한 글임을 미리 알립니다.

📜 바쁜 현대인을 위한 3줄요약

1. 학교(42Seoul) 인트라 API를 사용해 기능을 구현하는 토이프로젝트를 진행했는데 문서의 가이드라인을 읽어도 OAuth 로그인이 계속 서버단에서 실패가 됨.
2. 알고보니 가이드라인에서 필요하다고 (Required) 적혀있지 않은 항목을 필요로 했음
3. 여차저차 OAuth로 토큰 받아오니 문서가 너무 허술하고, 복잡하고, 애매하게 작성되서 일일이 모든 경로를 테스트 하느라 2~3일을 날림

🧸 기 : 이틀을 예상한 토이프로젝트

저는 현제 42Seoul에서 본과정 교육을 받고있는 학생입니다. 코로나가 연초와는 다르게 많이 잠잠해져서 교육장에 나와 동료학습을 시작했는데, 특히 동료평가를 할 때마다 인트라 사이트에 들어가서 평가를 해야 할 동료의 위치를 확인하는 과정이 번거로워 동료의 위치를 알려주는 서비스를 만들자고 생각이 들었습니다. 이왕 그런 서비스를 만들바에, 동료평가와 관련된 도움을 주는 서비스를 만들자고 기획하고 토이 프로젝트 Eval42를 진행했습니다.

기획 단계에서 이 프로젝트에서 구현해야하는 기능들을 정의했을 때, 이렇게 정리했습니다.

• 동료평가 시 동료의 위치를 한번에 조회
• 동료평가 가능 일정 등록 모바일 지원
  인트라 사이트를 모바일로 들어갔을 때 평가 일정을 등록하는 기능이 작동하지 않습니다. PC환경에서는 일정표를 마우스로 드래그해서 등록하는데, 모바일에서 드래그 기능이 작동하지 않습니다. 가장 좋은 건 인트라 사이트 오류 수정이지만, 프랑스인의 일처리는 매우 느리다는 점을 안지 오래전이라서 ㅎㅎ...
• 프로젝트 별 동료평가 팁 공유 포럼

솔직히 세번째 기능을 제외하고는 나머지 두 기능은 하루 날잡아서 해커톤 형식으로 끝낼 수 있다고 생각했습니다. 42에서는 인트라넷 정보를 이용하는 API를 제공하고 있다고 들었고, 이를 활용한 여러 서비스들이 현재 진행 & 완료 되었기 때문에 API에서는 별 문제없이 정보를 가져오면 되겠다고 생각했습니다... 다만 그 점은 너무나 큰 착각이였습니다.

🧐 승 : API에 대한 100%의 맹신?

프로젝트 리포지토리의 기본적인 설정을 끝내고, 본격적으로 42API의 문서를 읽어보기 시작했습니다. 프로젝트에서 인트라 아이디를 이용해 로그인을 한 이후, 사용자 토큰을 사용해 정보를 API를 통해 가져와야 함으로 API가 제공하는 OAuth 설정을 시작했습니다. 위 사진 하단에 있는 'Get Started' 링크를 통해 'Web application flow' 글을 참고하여 OAuth를 설정하며 로그인 링크를 테스트를 하니 다음과 같은 오류를 마주치게 되었습니다.

🤔 엥 뭐지? 난 올바른 uri 값을 쿼리에 넣었는데??

이렇게 생각해서 계속 찾아보다, API 설정 페이지에 나와있는 예시 주소값이 %xx%xx로 이루어져 있어 URLEncoded까지 찾아봐서 내부 소스에 대입시켜 넣어도 문제가 해결되지 않았습니다. 이때 뜻밖의 생각을 하게 되었습니다.

🤔 API 설정 페이지에 redirect uri를 쓰는 칸이 있던데...? 엥???

바로 현제 테스트 중인 redirect uri를 칸에 넣어 다시 테스트 해 보니 정상 작동되었습니다! 이 API의 숨겨진 규칙 을 하나 찾게 되었습니다. 바로 API 설정 페이지에 등록되어 있지 않는 uri는 사용할 수 없다는 것이였습니다! 이를 확인한 이후 문서에 이와 같이 적혀있는지 한 5번 넘게 확인했는데, 이와 관련된 내용은 전혀 작성되어있지 않았습니다!! 또한, 위 에러 페이지에 나와있는 에러 문구로는 유추하기 힘든 규칙이기도 합니다. (not valid 라고 했을 때 보통 형식이 잘못되었거나 주소로 접근할 수 없는 값인가 생각이 먼저 들지 않나요?)

사실은 API 등록할 때 한번 지나친 페이지라 어떻게든 유추해서 하면 되는거니깐 백번 이해하고 계속 진행했습니다. Oauth 연동을 하신 분들은 아시겠지만, API 서버가 사용자에게 전달한 임시 코드를 저희 서비스단으로 넘겨주면, 저희 서비스에서 임시 코드를 API 서버에게 넘겨주면 최종적으로 API 서버에게 토큰값을 전달받게 됩니다. 이 과정에서 또 한번의 오류가 발생했습니다!

아무리 해도 오류가 해결되지 않아 제가 OAuth를 사용할 때 문제가 있는건지 OAuth도 공부하기도 하고 관련 강의를 통으로 다시 들으면서 수정해보고 이리저리 볶아봤는데도 작동이 되지 않는겁니다... 그래서 지푸라기라도 잡아볼까 42API를 사용하는 다른 서비스를 만드신 분에게 슬랙으로 물어보니 아주 간단한 답변이 나오게 되었습니다.

😨 전 : 현타

또 다른 숨겨진 규칙 이였습니다. 그것은 바로 토큰을 요청할 때에는 redirect_url을 또 보내줘야 한다는 것 이였습니다. 다시 그 문서를 보러 가보니 redirect_url은 분명 Required라는 글이 적혀있지 않았습니다. 거의 이 오류로 하루를 갈아넣었는데 정말 간단한 결론으로 해결이 났습니다. 문서가 정확하지 않다는 것이였죠.

이후 다시 한번 API문서를 전체적으로 읽어보았습니다. 호출 경로가 너무 복잡하게 정리되어 있었습니다. 예를 들어 /user로 호출되는 내용이 User 메뉴에 있지 않고, /user/A의 경우 A메뉴에, /user/B의 경우 B메뉴에 아주 폭넓게(!) 엉켜있었습니다. 또한, 요청시 나오는 유일한 id값들이 많이 나오는데, 이중 어떤 값을 API를 호출할 때 넣어야 하는지 애매하게 적혀있었습니다. 마지막으로, 거의 대부분의 결과값 형식은 작성되어있지 않았습니다. 오로지 요청 Params만 명시가 되어있고 어떤 값이 리턴되고, 그 값은 각각 무엇을 뜻하고, 에러가 날 때엔 어떻게 결과가 나오는지 전혀 명시가 되어있지 않았습니다.

이 순간 직감했습니다. 이 프로젝트는 꽤 걸리겠다고요...

이에 질세라, 프로젝트의 큰 걸림돌이 발생했습니다. 글 초반에 이야기했던 기능 3가지 기억나시나요? 그 중 이 프로젝트를 시작한 계기인 동료평가시 동료의 위치 한번에 파악 이 기능을 위한 api 요청 경로를 찾는 중 동료평가와 관련된 모든 정보는 staff 이상의 권한만 조회 가능이라는 청천벽력과 같은 문서를 발견했습니다. 저는 개발 초기 '당연히 인트라에서도 조회 가능한 동료평가 정보니 API를 통해서 가져올 수 있겠지?' 라는 생각을 했는데 전혀 아니였습니다. 아무리 조회를 해도 권한이 없어 접근할 수 없다라는 에러 메세지만 나왔습니다.

그 이후 현타가 씨게 와 프로젝트를 잠시 접어두고 다른일을 하다가, 작성일 기준 그저께 (7/31)에 되서야 기본적인 기능들을 구현하고 배포까지 완료했습니다.

👿 결 : 프로젝트 1차 완료, 그 이후

기본적인 기능들이라고 해봤자, 다시 초기에 기획했던 3가지 기능을 나열하면서 설명하자면

• 동료평가 시 동료의 위치를 한번에 조회
  ❌ 현제 불가능, 복잡한 API문서를 다시한번 찾아 대체점을 찾거나 인트라를 크롤링하는 식으로 시도할 예정
• 동료평가 가능 일정 등록 모바일 지원
  🔺 구현하였으나 시간이 부족해 모바일에 최적화된 UI(반응형) 미구현
• 프로젝트 별 동료평가 팁 공유 포럼
  ❌ 시간이 부족해 다음 2차로 진행시 구현할 예정

기획한 내용을 100프로 완수하지 못해 매우 아쉬웠지만 저의 개인적인 사정과 이후 다른 42Seoul Cadet분들과 같이 팀프로젝트로 진행한다면 더욱 발전할 수 있다고 생각되기 때문에 여기까지 구현하고 1차 배포를 진행했습니다.

⏰ 이번 시간낭비(?)로 배우게 된 점

문서화는 매우*100 중요하다

API를 만들거나, 지금과 같이 개별 프로젝트를 할 때에도 다른 사람과 같이 코딩을 하다보면 각자 생각하는 점이 다를거고, 결국 정리해 문서로 만드는게 매우 중요하다고 이전부터 생각했지만, API를 사용하는 입장에서 이상한 문서를 가지고 코딩을 진행하다 보니 문서화의 필요성을 아주 뼈져리게 느꼈습니다.

API를 사용하기 전 문서를 꼭 읽자

이번과 같이 이상한 문서라도 원하는 기능에 대해선 한번씩은 읽고 개발에 시작해야 될 것 같다고 생각이 들었습니다. 만약 프로젝트를 시작하기 이전에 동료평가 정보를 가져올 수 없다는 정보를 알았더라면 조금 더 다른 방향으로 프로젝트를 진행하고, 시간 낭비를 안 하지 않았을까 후회되기도 합니다 😢

✅ Eval42가 궁금하다면?

• 배포 사이트 : https://eval42.herokuapp.com
• 깃헙 : https://github.com/cos18/eval42

개발 정비 & 제 프로젝트의 문서화도 진행한 이후 다른 42Seoul Cadet분들과 함께 2차 개발을 진행할 예정입니다. 완성이 되면 글을 통해 이 프로젝트에 대한 이야기를 남겨보도록 하겠습니다!