API 명세서 작성하기

예전에 api 관련 글을 쓴 적이 있다.

https://100won-developer.tistory.com/21

API란 무엇인가 (+REST API)

이때는 api에 대해서 간단히 알아보고 rest api는 무엇인지, 전체적인 맥락을 가볍게 훑어보았다. 이번에는 API 명세서 작성하는 방법을 써보려고 한다.

 

API 명세서란??

  API (Application Programming Interface) 명세서는 소프트웨어 개발자들이 서로 다른 시스템이나 프로그램 간에 상호작용할 수 있도록 인터페이스를 정의하는 문서이다. API 명세서는 일반적으로 API를 사용하는 방법, 인자(argument)와 반환(return)값의 형식, API를 호출할 때 예상되는 결과 등을 써놓는다. 또한 API 사용자들이 발생할 수 있는 문제들과 그것들에 대한 해결 방법을 제공할 수도 있다.

  API 명세서는 개발자들이 API를 쉽게 이해하고 사용할 수 있도록 예제 코드와 함께 제공되기도 한다. 이러한 명세서는 개발에서 중요한 역할을 한다. 왜냐하면 명세서를 보고 API를 사용하는 다른 개발자나 시스템과의 상호작용이 원활하게 이루어지고, 잘못된 사용이나 잠재적인 문제들을 방지할 수 있기 때문이다.

API 명세서 예시. api명세서를 작성하는 툴은 여러가지가 있고, postman에서 작성하기도 가능하지만 위 사진은 notion에서 작성한 모습이다.

API 명세서 작성 요령, 주의사항

API명세서는 정확한 틀이 있는 느낌은 아니라 팀원들과 협의해서 달라지기도 한다. API명세서를 다 만들고 시작하기도 하고 기능을 구현하면서 다음 기능에 대한 명세서를 작성하기도 하는 것으로 느꼈다. 다만 어떤 데이터를 주고받을지, URI를 어떻게 설정할지, 어떤 기능을 넣을지 같은 내용들은 필수적으로 들어가야 한다. 아래는 필자가 공부하면서 느낀 API 작성 방식이다. 회사에서 일해본 것도 아니고 그냥 팀프로젝트를 하며 느꼈던 API명세서 작성방식이라, 틀린 점이 있을 수도 있다. 하지만 맥락은 비슷할 것이라고 생각된다.

• API 명세서에서 가장 중요한 것은 기능설명, 메소드, requestbody, responsebody 정도인 것 같다. 메소드라는 것은 GET매핑일지 POST매핑일지 설정하는 것을 말한다. GET이나 POST나 DELETE같은 것들은 잘 구분이 되므로 우리는 PUT과 PATCH만 구분해서 잘 써주면 될 것 같다. 이 구분법은 아래 링크를 참고한다

https://100won-developer.tistory.com/60

PUT과 PATCH의 차이점

• 팀에서 RestAPI 방식을 따른다면, RequestBody 또한 JSON형태로 넘겨줘야하기 때문에 명세서에도 JSON 형태에 맞게 작성해준다. 다만, RequestBody가 확정난 경우에만 즉 어떤 데이터를 넘겨줘야하는지 확실해졌을 때에만 RequestBody를 적어주는 것이 좋고 그게 아니라면 프론트엔드가 헷갈릴 수 있기 때문에 아예 빼놓기도 한다고 한다. → 확정내는것은 보통 PM과 협의를 해서 내는 편이고, 디자인 팀에서 GUI가 완성이 되면 그때 확정나는 것 같다.
• ResponseBody는 웬만한 경우에 다 적어주는 편인데, GET으로 어떤 페이지에 접근한다고 할 때에도 해당 페이지에 어떤 정보들을 넘겨줘야하는지 알아야하기 때문이다. 백엔드에서 ResponseBody를 넘겨주는 것은 조금 복잡하기도 하다. 내가 배우기로는, 백엔드에서 responsebody와 http status를 설정할 때 정말 여러 형태의 오류를 다 분석해서 적어줘야 하는데 이때 유효성 검사를 해서 각각의 오류에 대한 상태코드를 다 알려줘야 한다. 그런데 이런 오류가 너무 많기 때문에 프론트와 협의해서 처음엔 적당히 조금만 써놓고, 일단 정상경로로 들어오는 로직부터 짠 후에 나중에 프론트와 함께 예외처리를 생각하는 것 같다. 그리고 이때 responsebody를 쓸 때에는 보여주는 정보랑 http status를 같이 넘겨주는 것이 좋아서 ResponseEntity를 사용하는 것이 좋다고 한다.
• 명세서를 작성할 때 GET 부분은 보통 requestbody 자체를 쓰는 게 아니라 URI 부분에 쿼리스트링으로 빼서 쓰는 경우가 많다고 한다. GET할 때에는 보여줄 데이터가 보통은 적은 경우가 많아서 쿼리스트링으로 빼고, responsebody는 우리가 어떤 데이터를 보여줘야 하는지 알아야하므로 꼭 적어주어야 한다. / 굳이 나누자면 GET에서는 responsebody와 쿼리스트링을 적고 , POST에서는 requestbody를 적어준다.