API와 API 명세서란?

* 프로젝트 진행 중 친구들에게 설명하기 위해 작성한 포스트입니다. 내용에 오류가 있을 수 있습니다.

---

API: 소프트웨어 애플리케이션 간에 통신을 가능하게 하는 인터페이스. (Application Programming Interface)

기능과 연결지어 이해하면 된다.

기업이 제공해서 개발자가 사용할 수 있는 API의 예시로는 '로그인 API', '지도 API', '결제 API', '챗봇 API' 등이 있으며, 궁금한 API를 검색하면 설명 문서를 쉽게 찾아 읽을 수 있다.

API를 통해 개발자들은 어려운 기술을 요하는 기능을 직접 개발하지 않고도 편리하게 사용할 수 있다.

API 명세서: API를 명확하고 자세하게 적어놓은 문서.

API를 사용하기 위해 필요한 정보를 확인할 수 있다.

나는 API를  마법 스킬과 같은 느낌으로 이해하고 있다. 마법사들은 마법을 발동하기 위해서 주문을 외우거나 그리며, 마도서를 통해 마법의 발동 방법과 주의사항 등을 확인한다. 어떤 마법을 만들었는데 발동주문을 알려주지 않으면 다른 사람들은 마법을 쓸 수 없을 것이다.

 

API도 비슷하다. 사용 방법 설명을 위해 기능, 사용 방법, 형식 등이 적힌 문서를 작성해야 한다.

(특정 형식을 갖추고 있다. HTTP Method 종류, 엔드포인트, 변수, 응답 형식 등...)

 

우리가 개발 프로젝트에 앞서 기능 정리를 위해 작성해야 하는 'API 명세서'의 API들은 위의 기업 API들보다 매우 소소한 규모이다.

'로그인', '친구 추가', '친구 목록'과 같은 기능들의 경우 프론트엔드와 서버 간에 통신이 필요하고. 이때 API를 사용한다.

 

개발에 앞서 API 명세서를 작성하면, 백엔드가 구현해야 하는 기능들을 정리할 수 있으며 또한 프론트엔드는 어느 부분에서 백엔드와 정보를 주고받아야 하는지 원소통할 수 있다. 명세서를 적다 보면 기획 중에는 미처 생각하지 못했지만 반드시 구현해야만 하는 기능을 추가하게 되기도 한다.

 

참고할 자료: 

https://it-roheerumi.tistory.com/31

[HTTP] 04. REST API 문서 작성