2년전 나에게 - API도 모르는데 명세서?

박민기·2025년 7월 7일

2년전 나에게

목록 보기

3/6

A. 배경

이 글은 첫 프로젝트에서 API명세서를 작성하는 과제를 받은 학생을 위한 글입니다.첫 프로젝트에서 API에 대해 잘 모르는데, API 명세서를 작성해오라는 과제를 받았습니다. 당시 저는 API에 대한 지식이 전혀 없어서,'API 명세서를 작성하라' 는 말을 들었을 때 머릿속에 물음표가 가득했습니다.
'통신을 하는 걸 명세하라는 건가?', '보고서처럼 작성해야 하나?' 등 여러 생각이 들었지만, 정작 무엇을 어떻게 작성해야 하는지 몰라 이것저것 검색해보았습니다. 하지만 대부분 문서 형태로만 설명되어 있었고, 이게 진짜 의도한 바가 맞는지, 무엇을 위한 명세서인지 혼란스러웠습니다.

결국 제대로 된 API 명세서를 작성하지 못했고, 그 결과 개발 과정에서 통일성이 없어졌습니다. 개발 실력도 부족한 상태에서 통일성 없는 개발을 하다 보니, API를 계속 수정하게 되었고, 오히려 프로젝트 기간만 늘어나는 상황이 벌어졌습니다.

이 글을 읽는, 저처럼 API 명세서를 처음 작성해보는 분들이라면, 통일성 있는 API 명세서를 통해 개발 시간을 단축하고, 원하는 데드라인에 맞춰 프로젝트를 완수할 수 있기를 바랍니다.

B. 기본 개념

1. API

API란 무엇인가?

API는 Application Programming Interface의 약자로, "어플리케이션 프로그래밍에서의 인터페이스" 역할을 합니다.
여기서 인터페이스란, 두 시스템이 데이터를 주고받을 때 지키는 '약속' 이라고 이해하면 쉽습니다.
즉, API는 두 시스템(예: 프로그램과 프로그램) 간에 데이터를 주고받을 때의 규칙이나 방법을 정의한 것입니다.

음식점 예시로 이해하는 API

음식점에서 손님이 웨이터에게 주문을 하고, 웨이터는 그 주문을 주방장에게 전달해 음식을 받아 다시 손님에게 전달하는 과정을 생각해볼 수 있습니다.

손님(프론트엔드): 원하는 음식을 주문(요청)합니다.
웨이터(API): 주문을 받아 주방장에게 전달하고, 완성된 음식을 다시 손님에게 전달합니다.
주방장(서버): 주문서를 받아 레시피(로직) 대로 음식을 만들어 웨이터에게 전달합니다.

이처럼 웹 프로그래밍에서도 프론트엔드(손님)는 API(웨이터)를 통해 서버(주방장)에게 요청을 보내고, 서버는 처리 결과를 API를 통해 다시 프론트엔드에 전달합니다.

2. RestAPI

웹 개발에서 가장 널리 사용되고, 배우기 쉽고, 확장성과 이식성이 뛰어난 API 방식이 바로 REST API입니다. 많은 첫 프로젝트에서 REST API를 선택하는 이유도 바로 이 때문입니다.

REST API의 기본 개념

REST API는 서로 다른 프로그램(앱, 웹, 서버 등)이 정해진 주소(URL)와 명령어(HTTP Method)만 알면,
서로 정보를 편리하게 주고받을 수 있도록 해주는 약속(규칙)입니다.

누구나 주소와 명령어만 알면
복잡한 내부 구조를 몰라도
데이터를 요청하고, 저장하고, 수정하고, 삭제할 수 있는 표준화된 소통 방법입니다.

REST API 구성요소 – 음식점 비유로 쉽게 이해하기

엔드포인트(Endpoint):
음식점에서 메뉴판에 "제육볶음", "돈가스"처럼 각각의 음식이 고유한 이름을 가지고 있듯, 서버에도 각각의 정보(자원)에 접근할 수 있는 고유한 주소(URL)가 있습니다. 이 주소가 바로 엔드포인트입니다.
HTTP 메서드(Method):
음식점에서 단순히 주문만 하는 게 아니라, "주문하기"(생성), "주문 확인"(조회), "주문 변경"(수정), "주문 취소"(삭제) 등 다양한 행동을 할 수 있듯이, REST API도 각 엔드포인트에서 어떤 동작을 할지 정하는 명령어를 사용합니다. 대표적으로 GET(조회), POST(생성), PUT/PATCH(수정), DELETE(삭제) 등이 있습니다.
요청(Request)와 응답(Response):
손님이 "제육볶음 1인분 주세요"라고 요청하면, 주방은 음식을 만들어 "제육볶음 나왔습니다"라고 응답합니다. 이처럼 클라이언트(손님)가 서버(주방)에 요청을 보내고, 서버는 그에 맞는 응답을 돌려주는 구조입니다.
데이터 형식:
음식이 그릇에 담겨 나오듯, 서버와 클라이언트가 주고받는 정보도 일정한 포장(형식)으로 전달됩니다. 주로 JSON이라는 형식을 사용해 데이터를 주고받습니다.
상태 코드(Status Code):
음식점에서 "주문이 정상적으로 접수되었습니다", "없는 메뉴입니다", "주방 사정으로 제공이 어렵습니다"처럼 주문 처리 결과를 알려주듯, 서버도 요청이 성공했는지, 오류가 났는지 숫자 코드로 결과를 알려줍니다. 예를 들어 200(성공), 201(생성됨), 404(없는 메뉴), 500(서버 오류) 등이 있습니다.

이렇게 REST API는 메뉴판(주소), 주문 방식(메서드), 대화(요청/응답), 음식 포장(데이터 형식), 주문 결과(상태 코드)처럼 누구나 쉽게 이해할 수 있는 규칙으로, 앱과 서버가 정보를 주고받도록 도와줍니다

3. EndPoint

URL 구조

EndPoint URL은 위 그림과 같은 구조로 되어있고, 저희는 Port뒤에 있는 부분을 주목해서 보겠습니다.

Application Context: 서비스가 여러개일 때 구분자의 역할을 해줍니다. (이 부분은 프로젝트의 크기가 클 때 사용하지만 첫 프로젝트 기준으로는 신경쓰지 않아도 된다고 생각합니다.)
Version : API 버전은, 기존 손님(사용자)이 헷갈리지 않게 옛날 메뉴판을 그대로 두고, 새로운 메뉴(기능)는 새 메뉴판(버전)으로 따로 제공하는 것과 같다고 생각하면 좋을 것 같아요. 지속적인 업데이트가 되는 부분에서 주로 사용을 합니다.
Resource : 이 통신에서 데이터의 주체가 되는 것을 말합니다. 예를 들어 주문, 손님, 음식과 같은 주체를 기준으로 나누면 편합니다.

첫 프로젝트라면 이전 글에서 ERD에서 테이블을 기준으로 나눠줘도 됩니다.
간혹 화면을 중심으로 나누는 경우가 있는데 이렇게 할 경우 API를 재사용이 힘들고, 일관이 떨어질 수 있어서 주의해주세요.
Path Variable : URL의 경로에 포함되어 특정 리소스를 식별할 때 사용됩니다.
조금 더 쉽게 설명하자면, 음식점에서 3번 테이블에 앉아 주문을 할 때를 떠올려보세요.
이 경우, "/orders/3"과 같은 URL에서 orders는 주문이라는 리소스, 3은 3번 테이블을 가리킵니다.

URL 경로에 숫자나 이름 등 구체적인 값을 넣어,
"어떤 주문인지" 또는 "어떤 대상을 요청하는지"를 정확하게 지정하는 방식입니다.
Query Parameter : URL의 ? 뒤에 붙어 추가 옵션이나 검색, 필터링, 정렬 등에 사용되는 파라미터입니다.
조금 더 쉽게 설명하자면, 음식점 사장님이 배달로 들어온 주문 내역을 확인한다고 가정을 한다면
이 경우, "/orders?type=delivery"과 같은 URL에서 orders는 주문이라는 리소스가 되고 type=delivery는 이를 조회하기 위한 조건이 됩니다.

Path Variable 과 Query Parameter가 비슷하다고 생각을 한다면

Path Variable은 리소스를 식별할 수 있게 해주는 것과

Query Parameter 리소스의 속 옵션 이라고 생각하시면 좋을 것 같습니다.

4. Method

Method의 대표적인 것들 만 표로 살펴보면

이를 데이터베이스 쿼리 조회로 생각을 하시게 되면 GET(SELECT), POST(INSERT), PUT(UPDATE), PATCH(UPDATE), DELETE(DELETE)가 되고 URL이 어떤 목적성을 가지고 행동을 할 것 같은지에 대해서 생각을 하면 금방 답을 찾을 수 있으실 겁니다.

5. 상태 코드

상태코드는 서버가 요청을 받았을 때, 그 결과가 어땠는지 숫자로 알려주는 신호입니다.
마치 음식점에서

"주문이 정상적으로 들어갔습니다!"
"없는 메뉴입니다!"
"주방에 문제가 생겼어요!"

라고 알려주는 것과 비슷합니다.

프로젝트에서 많이 사용되는 상태코드를 표로 보여드리면 아래와 같습니다.

코드별 대처법

여기서 200번대가 왔다면 프론트 개발자분들 정말 잘하신겁니다. 성공하셨어요.

근데 400번대 코드가 왔다면, 프론트 개발에 뭔가 잘못 되었을 가능성이 큽니다. 명세서를 다시 확인해보세요. 나는 진짜 잘못한거 없는데? 라면 그건 백엔드가 명세서를 안지킨거에요. 카톡 보내셔도 됩니다.

500번대가 코드가 왔다면, 그냥 바로 백엔드 개발자분께 연락하세요.서버에서 뭔가 잘못되었을 겁니다.

6. Request/Response, 데이터 형식

API를 설계할 때 많은 개발자들이 구조, 성능, 보안 등 다양한 요소를 고민합니다. 하지만 실제로 프론트엔드와 백엔드가 가장 많이 부딪히는 부분은 바로 데이터 형식입니다. 이 글에서는 왜 데이터 형식의 통일이 중요한지, 그리고 이를 어떻게 적용하면 좋은지에 대해 이야기해보겠습니다.

데이터 형식이 중요한 이유

서로 다른 팀이 협업할 때, 혹은 한 사람이 프론트와 백엔드를 모두 개발할 때도, API의 데이터 형식이 일관되지 않으면 코드가 불필요하게 복잡해집니다. 예를 들어, 음식점에서 비슷한 메뉴를 모두 다른 그릇에 담아 내보낸다고 생각해보세요. 설거지와 보관, 재사용이 모두 비효율적이겠죠. API도 마찬가지입니다.

일관된 형식은 프론트엔드에서 데이터를 파싱하고 상태를 관리하는 코드를 단순화합니다.
재사용성이 높아집니다. 공통된 파싱 함수, 상태 관리 로직을 여러 곳에서 활용할 수 있습니다.
유지보수가 쉬워집니다. 새로운 API가 추가되어도 기존 로직을 그대로 사용할 수 있습니다.

공통 응답의 예시입니다.

{
  "status": "{상태코드}",
  "success": true,
  "data": "{반환값}"
}

이렇게 하면 프론트엔드와 백엔드 모두 아래와 같은 장점을 누릴 수 있습니다.

프론트엔드: 항상 같은 구조로 데이터를 받아오기 때문에, 공통 파싱 함수로 모든 API 응답을 처리할 수 있습니다.
백엔드: 응답을 만들 때 매번 새로운 구조를 고민할 필요 없이, 정해진 그릇에 값만 담아주면 됩니다.

키 네이밍도 통일하자

키 이름이 userId, useRId, userid처럼 제각각이면, 프론트엔드에서 상태 관리 변수나 파싱 로직을 재사용하기 어렵습니다. 키 네이밍 컨벤션을 팀 내에서 미리 정해두는 것이 중요합니다.

예시: 항상 userId로 통일
API 문서에 명확하게 표기

서로를 배려하는 API 설계

API를 설계할 때 "나는 이렇게 주면 편해"가 아니라, 상대방이 어떻게 받을지 한 번 더 고민해보세요. 프론트엔드는 어떤 데이터 구조가 파싱하기 쉬울지, 백엔드는 어떤 구조가 유지보수에 유리할지 서로 의견을 나누며 합의점을 찾아가는 과정이 중요합니다.

상황에 따라 트래픽, 성능, 보안 등 우선순위가 달라질 수 있습니다.
하지만 기본적으로 통일된 데이터 형식은 협업의 효율성을 극대화합니다.

REST API에서 Request/Response 데이터 형식의 통일은 프론트엔드와 백엔드 모두의 생산성을 높이고, 코드의 재사용성과 유지보수성을 크게 향상시킵니다. 작은 습관이지만, 프로젝트의 규모가 커질수록 그 효과는 더욱 커집니다. 데이터 형식을 통일하는 습관을 가지는 것이 좋습니다.

C. 마무리

저도 처음에는 API 명세서라는 게 너무 막막하고, 어디서부터 어떻게 시작해야 할지 정말 감이 안 잡혔던 기억이 납니다. 하지만 이렇게 하나씩 개념을 정리하고, 음식점 비유처럼 일상적인 예시로 이해하려고 노력하다 보면 어느새 머릿속에 API의 큰 그림이 그려지기 시작하더라고요.

사실, API 명세서 작성이란 게 거창하거나 어려운 일이 아닙니다. 서로 간에 "이런 방식으로 소통하자!"고 약속을 정하는 거고, 그 약속이 잘 지켜지면 개발도 훨씬 수월해집니다. 처음에는 다소 낯설고 헷갈릴 수 있지만, 한 번 제대로 경험해보면 다음부터는 훨씬 쉽게, 또 자신감 있게 작성할 수 있을 거예요.

무엇보다 중요한 건, 혼자서 끙끙대지 말고 궁금한 점이 있으면 팀원들과 적극적으로 소통하는 겁니다. 명세서도 결국 협업을 위한 도구니까요. 그리고 데이터 형식, 키 네이밍, 상태 코드 등 사소해 보이는 부분도 팀 내에서 미리 통일해두면 나중에 훨씬 덜 힘들어집니다.

이 글을 읽으신 분들도 저처럼 시행착오를 줄이고, 통일성 있는 API 명세서를 통해 프로젝트를 더 효율적으로, 즐겁게 완성하실 수 있기를 진심으로 응원합니다! 앞으로도 개발하면서 궁금한 점이 생기면 주저하지 말고 검색하고, 질문하고, 서로 도와가며 성장해나가세요. 여러분의 첫 API 명세서 경험이 좋은 출발점이 되길 바랍니다.

아직 많이 부족하지만 더 좋은 글을 써서 도움이 되도록 노력해보겠습니다. 감사합니다.
다음 블로그 글은 "ERD와 명세서 작성에 활용했던 툴"에 대해서 소개해드릴게요.

박민기

밍기적거리지 않기

이전 포스트

2년전 나에게 - ERD 설계의 기본개념

다음 포스트

2년전 나에게 - API도 모르는데 명세서?