IT 기획자를 위한 API란? 개발자 회의 전에 꼭 알아야 할 실무 개념
IT 기획자를 위한 API란? 개발자 회의 전에 꼭 알아야 할 기본 개념
API는 개발자만 알아야 하는 기술 용어가 아닙니다. IT 기획자에게 API는 화면과 데이터가 어떻게 연결되는지 이해하기 위한 실무 개념입니다. 이 글에서는 API를 코드가 아니라 화면정의서, 요청값, 응답값, 개발자 회의 관점에서 쉽게 정리합니다.
IT 기획 업무를 하다 보면 개발자 회의에서 API라는 말을 자주 듣게 됩니다.
“이 화면은 API로 조회하면 됩니다.”
“응답값에 포함되어야 합니다.”
“요청값이 없으면 처리하기 어렵습니다.”
“이 데이터는 프론트에서 가지고 있는 게 아니라 서버에서 내려줘야 합니다.”
말은 익숙한데, 막상 화면정의서에 무엇을 써야 할지 막막할 때가 있습니다. 이때 필요한 것은 개발자처럼 코드를 작성하는 능력이 아닙니다. IT 기획자에게 필요한 것은 화면에서 어떤 데이터를 요청하고, 어떤 데이터를 받아서, 사용자에게 어떻게 보여 줄지 정리하는 능력입니다.
API는 어렵게 보이지만, 기획자 관점에서는 생각보다 단순합니다. 화면이 서버에 무언가를 요청하고, 서버가 그 결과를 다시 화면에 돌려주는 약속입니다. 화면 뒤에서 데이터들이 작은 택배 상자를 들고 뛰어다니는 구조라고 보면 됩니다.
API를 기획자 관점에서 이해하기
API는 Application Programming Interface의 줄임말입니다. 개발 관점에서는 프로그램이나 시스템끼리 데이터를 주고받기 위한 인터페이스라고 설명할 수 있습니다. 하지만 IT 기획자 입장에서는 조금 더 실무적으로 이해하는 것이 좋습니다.
API는 화면이 필요한 데이터를 서버에 요청하고, 서버가 그 결과를 화면에 돌려주는 약속입니다.
예를 들어 사용자가 쇼핑몰 앱에서 “주문 내역” 버튼을 누른다고 생각해 보겠습니다. 사용자는 단순히 버튼을 눌렀을 뿐이지만, 화면 뒤에서는 이런 일이 일어납니다.
- 화면이 서버에 주문 내역을 요청합니다.
- 서버는 로그인한 사용자의 주문 정보를 찾습니다.
- 서버는 주문번호, 상품명, 주문일자, 결제금액, 배송상태를 화면에 보내 줍니다.
- 화면은 받은 데이터를 사용자가 볼 수 있는 형태로 보여 줍니다.
이 과정에서 화면과 서버가 데이터를 주고받는 약속이 API입니다.
따라서 기획자가 API를 이해한다는 것은 어려운 기술을 모두 외운다는 뜻이 아닙니다. 내가 기획한 화면이 어떤 데이터를 필요로 하는지, 그 데이터를 언제 요청해야 하는지, 응답받은 데이터를 어떻게 보여 줄지 정리할 수 있다는 뜻입니다.
IT 기획자가 API를 알아야 하는 이유
IT 기획자는 화면의 문구, 버튼, 배치만 정하는 사람이 아닙니다. 실제 서비스에서는 화면 뒤에서 데이터가 계속 움직입니다. 이 데이터 흐름을 고려하지 않으면 기획서는 보기에는 괜찮지만 개발 단계에서 계속 질문이 발생합니다.
예를 들어 화면정의서에 아래처럼만 적었다고 해보겠습니다.
마이페이지에 회원 정보를 노출한다.
이 문장은 짧고 깔끔해 보입니다. 하지만 개발자는 바로 여러 질문을 하게 됩니다.
- 회원 정보 중 어떤 항목을 보여 줘야 하나요?
- 이름, 이메일, 휴대폰 번호, 가입일을 모두 보여 주나요?
- 휴대폰 번호는 전체 노출인가요, 일부 마스킹인가요?
- 소셜 가입자는 비밀번호 변경 버튼을 보여 주나요?
- 로그인이 만료된 사용자는 어떻게 처리하나요?
- 회원 정보를 불러오지 못하면 어떤 메시지를 보여 주나요?
이 질문들은 모두 API와 연결됩니다. 어떤 데이터를 요청할지, 어떤 데이터를 응답받을지, 데이터가 없거나 오류가 발생했을 때 어떻게 처리할지 정해야 하기 때문입니다.
API를 직접 개발하는 사람은 개발자입니다. 하지만 API가 어떤 데이터를 다뤄야 하는지, 어떤 화면 조건에서 필요한지, 어떤 예외 상황을 고려해야 하는지 먼저 정리하는 사람은 기획자입니다.
API를 이해하면 개발자와의 회의에서 질문을 받기만 하는 상태에서 벗어날 수 있습니다. “이 화면에서는 이 데이터가 필요합니다”, “이 케이스에서는 빈 화면 문구가 필요합니다”, “로그인이 만료되면 로그인 화면으로 보내야 합니다”처럼 기획 의도를 더 구체적으로 전달할 수 있습니다.
API는 요청과 응답의 약속이다
API를 처음 이해할 때는 복잡한 용어보다 요청과 응답만 기억하면 됩니다.
| 구분 | 기획자 관점의 의미 | 실무 예시 |
|---|---|---|
| 요청 | 화면이 서버에 필요한 데이터나 처리를 요구하는 것 | 주문 목록을 조회해 주세요 |
| 응답 | 서버가 요청 결과를 화면에 돌려주는 것 | 주문번호, 상품명, 결제금액, 배송상태 |
| 오류 응답 | 요청을 정상 처리할 수 없을 때 실패 사유를 돌려주는 것 | 로그인이 필요합니다, 정보를 찾을 수 없습니다 |
예를 들어 “쿠폰함” 화면을 기획한다고 해보겠습니다. 기획자는 단순히 쿠폰 목록 화면을 그리는 데서 끝나면 안 됩니다. 아래 내용을 함께 생각해야 합니다.
- 사용자가 어떤 메뉴를 눌렀을 때 쿠폰 목록을 조회하는가?
- 사용 가능한 쿠폰만 보여 줄 것인가?
- 만료된 쿠폰도 보여 줄 것인가?
- 쿠폰 정렬 기준은 만료일순인가, 발급일순인가?
- 쿠폰명, 할인금액, 사용기한, 사용 가능 여부가 모두 필요한가?
- 쿠폰이 없을 때 어떤 문구를 보여 줄 것인가?
이 질문들이 정리되어야 개발자는 API를 만들 때 필요한 기준을 잡을 수 있습니다. 결국 API 기획은 “어떤 데이터를 주고받을 것인가”를 정리하는 일입니다.
API는 화면이 서버에 보내는 질문이고, 응답은 서버가 화면에 보내는 답변입니다.
화면정의서에서 API를 어떻게 바라봐야 할까?
IT 기획자가 API를 볼 때 가장 중요한 기준은 화면입니다. API는 화면과 따로 떨어진 기술 문서가 아니라, 화면이 필요한 데이터를 주고받기 위한 연결 장치입니다.
화면정의서를 작성할 때는 다음과 같은 방식으로 API를 바라보면 좋습니다.
| 화면정의서 항목 | API와 연결되는 질문 | 기획자가 정리할 내용 |
|---|---|---|
| 화면 진입 조건 | 언제 데이터를 불러와야 하는가? | 화면 진입 시, 버튼 클릭 시, 탭 변경 시 |
| 노출 항목 | 응답값에 어떤 데이터가 필요한가? | 이름, 상태, 금액, 날짜, 개수 |
| 입력 항목 | 요청값으로 어떤 데이터가 필요한가? | 검색어, 기간, 카테고리, 사용자 선택값 |
| 버튼 동작 | 서버에 저장하거나 처리할 내용이 있는가? | 저장, 삭제, 신청, 취소, 재요청 |
| 빈값 처리 | 응답 데이터가 없을 때 무엇을 보여 줄 것인가? | 조회 결과 없음, 쿠폰 없음, 주문 내역 없음 |
| 권한 조건 | 누가 이 데이터를 볼 수 있는가? | 본인, 관리자, 작성자, 승인자 |
예를 들어 “공지사항 목록 화면”을 작성한다면 단순히 목록을 보여 준다고 쓰는 것보다 아래처럼 정리하는 것이 좋습니다.
공지사항 화면 진입 시 공지 목록을 조회한다. 목록에는 제목, 등록일, 중요 공지 여부를 노출한다. 중요 공지는 목록 상단에 먼저 노출하며, 공지사항이 없을 경우 “등록된 공지사항이 없습니다.” 문구를 표시한다.
이 정도만 작성해도 개발자는 API에 어떤 응답값이 필요하고, 어떤 정렬 기준이 필요한지 파악하기 쉬워집니다. 기획서가 개발 문서가 될 필요는 없지만, 개발자가 판단해야 할 중요한 조건을 빈칸으로 남겨 두면 일정이 삐걱거릴 수 있습니다.
기획자가 알아야 할 API 기본 용어
API 회의에서 자주 등장하는 용어를 기획자 언어로 정리하면 다음과 같습니다.
| 용어 | 기획자 관점의 의미 | 실무 예시 |
|---|---|---|
| 엔드포인트 | 특정 기능을 호출하는 API 주소 | 주문 목록 조회 API 주소 |
| 요청값 | 서버에 전달해야 하는 조건이나 데이터 | 검색어, 조회 기간, 주문 상태 |
| 응답값 | 서버가 화면에 돌려주는 데이터 | 주문번호, 상품명, 결제금액 |
| 파라미터 | 요청할 때 함께 보내는 조건값 | 페이지 번호, 정렬 기준, 카테고리 |
| 헤더 | 요청에 함께 전달되는 부가 정보 | 로그인 토큰, 콘텐츠 타입 |
| 바디 | 등록이나 수정 시 전달하는 본문 데이터 | 회원가입 정보, 게시글 내용, 배송지 정보 |
| 토큰 | 로그인한 사용자인지 확인하기 위한 인증 정보 | 로그인 유지, 사용자 권한 확인 |
기획자는 API 용어를 모두 외우는 것보다, 각 용어가 화면정의서의 어떤 항목과 연결되는지 이해하는 것이 중요합니다.
예를 들어 “요청값”이라는 말을 들으면 “사용자가 입력하거나 선택한 조건 중 서버에 전달해야 하는 값”이라고 이해하면 됩니다. “응답값”이라는 말을 들으면 “화면에 보여 주기 위해 서버에서 받아야 하는 값”이라고 이해하면 됩니다.
이 정도만 알아도 회의에서 개발자의 말을 훨씬 명확하게 따라갈 수 있습니다. 용어가 낯설어서 회의실 한쪽에서 조용히 얼음 조각이 되는 일을 줄일 수 있습니다.
API를 알면 기획서가 어떻게 달라질까?
API를 모를 때와 알 때의 기획서는 차이가 큽니다. 겉으로는 같은 화면정의서처럼 보여도, 개발자가 받아들이는 정보의 밀도가 달라집니다.
| 구분 | API를 고려하지 않은 기획 | API를 고려한 기획 |
|---|---|---|
| 주문 내역 | 주문 내역을 보여 준다. | 화면 진입 시 로그인 사용자의 주문 목록을 최근 주문일순으로 조회한다. |
| 쿠폰함 | 쿠폰 목록을 보여 준다. | 사용 가능한 쿠폰과 만료된 쿠폰을 구분하여 노출하고, 쿠폰이 없을 경우 빈 화면 문구를 표시한다. |
| 회원 정보 | 회원 정보를 보여 준다. | 이름, 이메일, 휴대폰 번호를 노출하되 휴대폰 번호는 가운데 자리를 마스킹한다. |
| 검색 화면 | 검색 결과를 보여 준다. | 검색어 입력 후 검색 버튼 클릭 시 결과를 조회하며, 결과는 최신순으로 노출한다. |
오른쪽처럼 작성하면 개발자는 어떤 데이터를 조회해야 하는지, 어떤 조건이 필요한지, 어떤 화면 처리가 필요한지 더 쉽게 이해할 수 있습니다.
화면에 보이는 모든 정보는 어딘가에서 와야 합니다. 사용자가 입력한 모든 정보는 어딘가로 가야 합니다. 이 오고 가는 길을 정리하는 것이 API 이해의 시작입니다.
마무리
API는 개발자만의 언어가 아닙니다. IT 기획자에게 API는 화면과 데이터가 만나는 지점입니다.
화면에 어떤 정보를 보여 줄지, 사용자가 어떤 조건을 선택하는지, 서버에서 어떤 데이터를 받아야 하는지 정리하는 과정에서 API 이해는 반드시 필요합니다.
개발자처럼 코드를 알 필요는 없습니다. 대신 기획자는 다음 네 가지를 명확히 해야 합니다.
- 사용자가 어떤 행동을 하는가?
- 화면은 어떤 데이터를 요청하는가?
- 서버는 어떤 데이터를 응답해야 하는가?
- 데이터가 없거나 조건이 맞지 않을 때 어떻게 보여 줄 것인가?
이 네 가지를 정리할 수 있다면 API 회의에서 훨씬 단단하게 이야기할 수 있습니다. API는 복잡한 기술 단어가 아니라, 기획서의 빈칸을 찾아주는 손전등입니다.
FAQ
Q1. IT 기획자가 API를 꼭 알아야 하나요?
개발자처럼 깊게 알 필요는 없습니다. 하지만 요청과 응답, 요청값과 응답값, 화면정의서와 API의 관계 정도는 이해하는 것이 좋습니다. 그래야 개발자와 회의할 때 필요한 데이터와 조건을 더 정확히 설명할 수 있습니다.
Q2. API를 모르면 화면정의서를 작성하기 어렵나요?
화면 구조만 작성하는 것은 가능합니다. 하지만 실제 개발 단계에서는 화면에 필요한 데이터, 조회 조건, 빈값 처리, 권한 조건이 필요합니다. API의 기본 개념을 알면 화면정의서를 더 실무적으로 작성할 수 있습니다.
Q3. API 명세서는 기획자가 작성해야 하나요?
일반적으로 상세 API 명세는 개발자가 작성합니다. 다만 기획자는 어떤 화면에서 어떤 데이터가 필요하고, 어떤 조건과 예외가 있는지 먼저 정리해야 합니다. 이 정보가 API 명세 작성의 기준이 됩니다.
Q4. 요청값과 응답값은 어떻게 구분하나요?
요청값은 화면이 서버에 전달하는 값입니다. 예를 들어 검색어, 조회 기간, 카테고리, 페이지 번호가 요청값이 될 수 있습니다. 응답값은 서버가 화면에 돌려주는 값입니다. 예를 들어 상품명, 가격, 주문일자, 배송상태가 응답값이 될 수 있습니다.
Q5. API를 이해하면 개발자와의 회의가 어떻게 달라지나요?
단순히 “이 화면을 만들어 주세요”라고 말하는 대신, “이 화면에서는 어떤 데이터를 조회하고, 어떤 조건으로 보여 주며, 데이터가 없을 때는 어떻게 처리한다”라고 설명할 수 있습니다. 그만큼 재질문과 재작업이 줄어듭니다.