[이룸] 240129 API 명세 작성에 대한 회고

api 는 수정, 수정, 또 수정…

 

팀장이기 때문에 더 책임감을 느끼기도 했지만, 지난번 프로젝트 때부터 api 문서의 중요성을 느껴왔기 때문에 다음과 같이 메모를 달며 수정을 진행하였습니다.

 

주고받을 정보가 추가, 수정, 삭제되는 경우도 많았지만, url과 변수명에 대한 고민도 있었습니다.

 

특히 URI의 경우, RESTful API의 설계 원칙에는 URI에 동사를 넣지 않고 http 메서드만을 활용하는 게 좋은 api 설계라고 이야기하지만, 그것만으로 모든 걸 표현하기에는 무리가 있기도 했습니다. 따라서 그때그때 상황에 맞추어 설계 원칙을 적용하고, 이를 팀원들과 합의하는 것이 중요하다는 결론에 이르렀습니다.

 

 

변수명 하나도 세심하게 고르려고 했습니다. 이전 프로젝트에서 변수명에 대한 합의가 제대로 이루어지지 않아 변수명이 불일치하는 경우가 생겼고, 이로 인해 에러가 나는 경우가 꽤 많았기 때문입니다. 제대로 합의되고 뜻이 명확한 변수명을 만들기 위해 노력하였습니다.

 

RESTful한 API란 도대체 무엇일까요? 각각의 데이터, 즉 자원이 어떻게 오고가며 관계를 맺는지 직관적으로 알 수 있다면, 설계 원칙에서 조금 벗어나더라도 충분히 RESTful한 API가 아닐까 합니다.

 

그런 점에서 부족한 게 많겠지만, RESTful한 API를 작성하겠다는 소기의 목적은 이루었다는 생각이 듭니다. 이를 위해 몇 시간씩 긴 회의를 버텨 준 팀원들에게 정말 고맙고 앞으로의 프로젝트에 정성들여 작성한 api 문서가 큰 도움이 되기를 바랍니다.