[개발 협업 심화] 개발자와 대화하기 위해 꼭 알아야 할 API 기초 지식

기획서에 '버튼 클릭 시 다음 화면으로 이동'이라고만 쓰면 개발자는 외계어를 만난 듯합니다. 개발팀과의 원활한 소통과 효율적인 기능 구현을 위해 기획자는 API(Application Programming Interface)를 이해해야 합니다. API는 단순히 기술 용어가 아닌, 서로 다른 시스템이 대화하는 '표준화된 언어'이자 기획자의 핵심 대화 수단입니다. 1. API, 왜 기획자가 알아야 하는가? - "막연함은 오해를 낳는다" API는 앱이나 웹 서비스의 '데이터 요청과 응답' 방식을 정의합니다. 기획자가 API를 모르면 "이게 돼요?", "저것도 돼요?" 같은 막연한 질문만 반복하게 되고, 개발팀은 답답함을 느낍니다. 정확한 기능 정의: 어떤 데이터를 주고받아야 하는지 명확히 이해하여 기능을 더 구체적으로 설계할 수 있습니다. 기술적 가능성 타진: "이런 데이터는 어디서 가져와야 해요?", "어떤 정보를 보낼 수 있어요?"와 같이 더 실질적인 질문을 던질 수 있게 됩니다. 효율적인 커뮤니케이션: 개발팀과 같은 언어로 소통하며 불필요한 재작업과 오해를 줄일 수 있습니다. 새로운 서비스 기획 아이디어: 외부 API를 활용하여 기존에 없던 새로운 서비스를 기획할 수 있는 시야를 넓혀줍니다. 2. 기획자가 알아야 할 API 핵심 개념 3가지 1단계: API는 "식당 주문"과 같다 (요청과 응답) 개념: API는 특정 기능을 수행하거나 데이터를 주고받기 위한 '정해진 약속'입니다. 마치 손님이 식당에 가서 메뉴를 주문하면, 주방이 주문에 맞춰 음식을 만들어 주는 것과 같습니다. 기획 포인트: 요청(Request): 사용자가 특정 행동을 했을 때, 서비스는 어떤 정보를 담아 서버에 요청할지 정의합니다. (예: "로그인" 요청 시 '아이디'와 '비밀번호'를 보냄) 응답(Response): 서버는 요청에 따라 어떤 결과를 사용자에게 돌려줄지 정의합니다. (예: "로그인 성공" 또는 "비밀번호 불일치") HTTP Method: 요청의 종류를 나타내는 동사입니다. GET: 데이터 조회 (예: 게시글 목록 가져오기, 사용자 정보 보기) POST: 데이터 생성 (예: 게시글 작성, 회원가입) PUT/PATCH: 데이터 수정 (예: 게시글 수정, 프로필 편집) DELETE: 데이터 삭제 (예: 게시글 삭제, 회원 탈퇴) 기획자의 활용: "이 기능은 서버에 데이터를 새로 만들어요(POST), 아니면 기존 데이터를 가져와요(GET)?"와 같이 질문하며 기능을 명확히 합니다. 2단계: "어떤 정보를 주고받을까?" - API 명세서 읽기 (데이터 구조) 개념: API 명세서는 '이 API를 호출하면 어떤 값을 보내야 하고, 어떤 값을 받을 수 있는지'를 정의한 문서입니다. 마치 메뉴판에 요리 재료와 가격이 적혀 있는 것과 같습니다. 기획 포인트: JSON 형식 이해: 데이터를 주고받는 표준 형식인 JSON(JavaScript Object Notation)의 기본적인 구조( {} 객체, [] 배열)를 이해합니다. Request Body/Query Parameter: 요청 시 어떤 데이터를 '본문'에 담아 보낼지, 어떤 데이터를 'URL'에 붙여 보낼지 구분합니다. 예시: GET /users?id=123 (id=123은 Query Parameter) POST /users 에 { "name": "홍길동", "age": 30 } 를 Request Body로 보냄 Response Body: 서버에서 응답으로 내려주는 데이터에 어떤 항목(필드)들이 있고, 각 항목의 데이터 타입(문자열, 숫자, 불리언)이 무엇인지 확인합니다. 예시: { "success": true, "user_name": "홍길동", "user_id": "gildong123" } 기획자의 활용: "상품 목록 API 응답에 가격 정보가 있나요?", "결제 요청 시 어떤 사용자 정보를 보내야 해요?"와 같이 구체적으로 질문할 수 있습니다. 3단계: "문제가 생기면 어떻게 될까?" - 에러 코드와 예외 처리 (Error Handling) 개념: API 호출 시 정상적인 응답 외에, 어떤 문제가 발생했는지 알려주는 약속된 코드와 메시지입니다. 기획 포인트: HTTP Status Code: 서버가 요청에 대해 어떤 상태를 응답했는지 알려주는 코드입니다. 2xx (Success): 성공 (200 OK 등) 4xx (Client Error): 클라이언트(요청하는 쪽) 오류 (400 Bad Request, 401 Unauthorized, 404 Not Found 등) 5xx (Server Error): 서버 오류 (500 Internal Server Error 등) 에러 메시지 기획: 각 에러 코드에 대응하여 사용자에게 어떤 에러 메시지를 보여줄지 미리 기획해야 합니다. (예: 401 에러 시 "로그인이 필요합니다" 메시지 노출) 기획자의 활용: "만약 사용자가 잘못된 값을 입력하면(400), 어떤 에러 코드를 받고 화면에는 뭐라고 보여줄까요?"와 같이 예외 상황을 미리 논의하여 사용자 경험을 설계합니다. 3. 기획자가 API 지식을 활용하는 실전 팁 개발팀에게 API 명세서 요청: 모든 기능 기획 시 해당 기능과 관련된 API 명세서를 미리 요청하여 읽어보는 습관을 들입니다. Postman/Swagger 활용: 개발팀이 주로 사용하는 API 테스트 툴(Postman, Swagger 등)을 곁눈질이라도 보며 익숙해지려고 노력합니다. 초기 단계부터 개발팀과 API 논의: 기능 기획 초반에 개발팀과 함께 API 스펙을 논의하여, 기획 단계에서 발생할 수 있는 기술적 문제나 비효율성을 미리 파악합니다. 포스팅 마무리 꿀팁 "API는 개발팀과의 '통역사'입니다. 통역사의 능력이 곧 협업의 품질을 결정합니다." API에 대한 기초 지식은 기획자와 개발자 사이의 벽을 허무는 강력한 도구입니다. 더 이상 개발팀의 말을 '기술 용어'로만 듣지 않고, 그들이 구축하는 '데이터의 흐름'을 이해하려 노력하는 순간, 여러분의 기획은 한 단계 더 단단하고 현실적인 설계가 될 것입니다.