10-1 API와 요청·응답 이해하기
1 / 1
10회 · 첫째 차시第 10 次课 · 第 1 课时

API와
요청·응답 이해하기
理解 API
与请求·响应

사용자의 행동이 요청이 되고,
처리 결과가 응답으로 돌아오는 과정을 읽습니다.
理解用户行动如何变成请求,
结果如何以响应返回。
이전 차시 · 9-2. 사용자 흐름·개발 계획 확정
다음 차시 · 10-2. AI와 핵심 API 연결
범위 · 내부 API 하나
上一课时 · 9-2. 确定用户流程与开发计划
下一课时 · 10-2. 与 AI 连接核心 API
范围 · 一个内部 API
들어가며开始之前10-1

버튼을 누른 뒤, 무슨 일이 일어날까?按下按钮后发生了什么?

할 일 추가 서비스待办添加服务

사용자가 “과학 보고서 쓰기”를 입력하고 추가를 누릅니다. 화면은 기능에 요청을 보내고, 기능은 결과를 응답합니다.用户输入“写科学报告”并按下添加。画面向功能发送请求,功能把结果作为响应返回。

핵심 질문核心问题

사용자의 행동은 어떤 요청이 되고,
서비스는 어떤 응답을 돌려줘야 할까?
用户行动会变成什么请求?
服务应该返回什么响应?

9회와 역할이 다릅니다与第 9 次课角度不同

9회는 사용자 전체 흐름을 설계했습니다. 10회는 핵심 행동 하나에서 요청과 응답이 오가는 방식을 볼 것입니다.第 9 次课设计了整体用户流程。第 10 次课聚焦一个核心行动中请求与响应的往返。

1. 개념1. 概念10-1

API는 약속된 창구다API 是约定好的窗口 핵심核心

APIApplication Programming Interface
화면과 기능이 서로 요청하고 응답하는 약속된 창구画面与功能之间发送请求、返回响应的约定窗口
주소地址어디에?发到哪里?
→
의도意图무엇을?做什么?
→
데이터数据무엇을 함께?带什么?
예例子의미意思
/api/tasks할 일을 다루는 약속된 주소处理待办的约定地址
추가添加새 할 일을 처리해 달라는 의도处理新待办的意图
task보낼 할 일 내용要发送的待办内容
작은 접수 창구. 한쪽에서 종이를 밀어 넣고 반대쪽에서 다른 종이가 나온다.
그림 10-1-1. 정해진 창구에 정해진 것을 내면, 정해진 것이 돌아온다.图 10-1-1. 在约定好的窗口交进约定好的东西,就会拿回约定好的东西。
2. 전체 과정2. 整体过程10-1

사용자 흐름을 요청·응답으로 읽는다用请求·响应阅读用户流程 핵심核心

① 사용자 행동입력하고 버튼을 누른다① 用户行动输入后按按钮
▼
② 요청화면이 API에 데이터를 보낸다② 请求画面向 API 发数据
▼
③ 처리서비스가 규칙대로 처리한다③ 处理服务按规则处理
▼
④ 응답결과나 안내를 화면에 보여 준다④ 响应在画面显示结果或提示
흐름을 다시 설계하는 것이 아닙니다不是重新设计流程

9회의 흐름은 그대로 유지합니다. 오늘은 그 중간에 오가는 데이터를 더 세밀하게 봅니다.第 9 次课的流程保持不变,今天只更仔细地看中间往返的数据。

지금 적는다现在写下来10-1

내 흐름 한 단계를 넷으로 쪼갠다把我的流程中的一步拆成四步 실습实践

9회에 적은 사용자 흐름에서 핵심 기능이 일어나는 단계 하나를 고릅니다. 그 한 단계를 위의 네 칸으로 쪼개 봅니다.从 9 次写的用户流程里,挑出核心功能发生的那一步。把那一步拆成上面的四格。

칸格내 서비스에서는在我的服务里
① 사용자 행동① 用户动作
② 화면이 보내는 것② 画面发送什么
③ 서비스가 하는 일③ 服务做什么
④ 화면에 나타나는 것④ 画面上出现什么

흐름을 다시 설계하지 않습니다. 9회에 적은 그 흐름의 한 단계를 그대로 가져와 안을 들여다보는 것뿐입니다.不是重新设计流程。只是把 9 次写好的那条流程中的一步拿过来,看看里面。

3. 방법3. 方法10-1

GET과 POST는 요청의 의도를 나타낸다GET 与 POST 表示请求意图 핵심核心

방법方法쉽게 말하면简单来说예例子
GET이미 있는 정보를 보여 달라把已有信息给我기록 목록 불러오기读取记录列表
POST데이터를 보낼 테니 처리해 달라我发数据,请处理새 기록 추가, 입력값 계산添加记录、计算输入值
생각해 보기想一想

“나의 독서 기록을 보여 줘”는 GET, “오늘 읽은 책을 기록해 줘”는 POST에 가깝습니다.“给我看阅读记录”更接近 GET,“记录今天读的书”更接近 POST。

암기보다 의도를 판단합니다不背,而是判断意图

기능이 정보를 받는 일인지, 데이터를 보내 처리하는 일인지만 판단하면 됩니다.只要判断功能是获取信息,还是发送数据并处理。

워크시트 ①工作表 ①10-1

이 행동은 GET인가 POST인가这个动作是 GET 还是 POST 실습实践

WORKSHOP ①요청의 의도 가리기区分请求的意图

이름을 외우는 것이 아닙니다. 이미 있는 것을 보여 달라는 일인지, 무언가를 보내 처리해 달라는 일인지만 판단합니다.不是背名字。只判断是「把已有的东西显示出来」还是「送点东西过去处理」。

#사용자가 하는 일用户做的事GET · POST왜 그렇게 봤나为什么这么看
1기록 목록을 불러온다载入记录列表
2새 기록을 추가한다添加新记录
3입력한 값으로 계산한다用输入的值做计算
4← 내 서비스의 핵심 행동← 我的服务的核心动作
확인确认
  • 세 번째 줄에서 계산도 POST라는 것을 확인했다. 보내서 처리하는 일이기 때문이다.第三行确认了计算也是 POST,因为是送过去处理。
  • 네 번째 줄은 내 서비스로 적었다.第四行是用自己的服务写的。
4. 데이터 형식4. 数据格式10-1

JSON은 ‘이름: 값’으로 데이터를 담는다JSON 用“名称:值”装载数据 핵심核心

JSON은 요청과 응답에서 데이터를 표현하는 방식입니다. Python의 사전과 비슷한 모양입니다.JSON 是请求与响应中表示数据的方式,外形与 Python 字典相似。

요청 JSON请求 JSON
{ "task": "과학 보고서 쓰기" }
응답 JSON响应 JSON
{
  "ok": true,
  "message": "할 일을 추가했습니다."
}
이름名称값值의미意思
task과학 보고서 쓰기写科学报告보낸 할 일发送的待办
oktrue처리 성공处理成功
message추가했습니다已添加화면의 안내画面提示
문법 연습이 아닙니다不是语法练习

괄호와 쉼표를 외우지 않습니다. AI가 제안한 내용에서 이름과 값의 의미를 읽습니다.不背括号和逗号,只读懂 AI 提议中名称与值的意思。

지금 적는다现在写下来10-1

내 요청과 응답을 이름:값으로把我的请求和响应写成「名称:值」 실습实践

괄호와 쉼표는 신경 쓰지 않습니다. 어떤 이름에 어떤 값이 들어가는지만 적습니다. 3-2에서 만든 이름표 묶음과 같은 모양입니다.不用管括号和逗号。只写哪个名称里放哪个值。和 3-2 做的名牌集合是一样的样子。

보내는 것 · 이름发送 · 名称값의 예值的例子
받는 것 · 이름接收 · 名称값의 예值的例子
oktrue 또는 falsetrue 或 false
message화면에 보여 줄 안내 한 줄要显示在画面上的一句提示

ok 와 message 는 거의 모든 서비스가 씁니다. 그대로 두고 내 서비스에만 필요한 이름을 아래 빈 줄에 적습니다.ok 和 message 几乎每个服务都用。保留它们,把自己服务特有的名称写在下面的空行里。

5. 응답5. 响应10-1

성공도 실패도 다음 행동을 알려줘야 한다成功与失败都要告诉下一步 핵심核心

결과结果응답의 내용响应内容화면의 역할画面作用
성공成功성공 여부와 결과是否成功与结果원한 결과 표시显示期望结果
입력 문제输入问题무엇을 고쳐야 하는지要修改什么수정과 다시 시도 방법修改与重试方法
서비스 문제服务问题처리하지 못했음未能处理사용자 탓으로 돌리지 않고 다시 시도 안내不归咎用户,提示重试
더 나은 안내更好的提示

“오류”보다 “할 일을 한 글자 이상 입력한 뒤 다시 추가해 보세요”가 더 유용합니다.比起“错误”,“请输入至少一个字后重试”更有用。

상태 코드를 외우지 않습니다不背状态码

사용자가 결과를 이해하고 다음 행동을 선택할 수 있는지만 확인합니다.只确认用户能否理解结果并选择下一步。

워크시트 ②工作表 ②10-1

이 안내를 받으면 다음에 뭘 할까收到这句提示,接下来该做什么 실습实践

WORKSHOP ②실패 안내 고쳐 쓰기改写失败提示

왼쪽 안내를 받은 사용자가 다음에 무엇을 할 수 있는지 판단합니다. 모르겠으면 다음 행동이 보이도록 고쳐 씁니다.判断收到左边提示的用户接下来能做什么。如果不知道,就改写成能看出下一步的样子。

#서비스가 보낸 안내服务发出的提示다음 행동을 알 수 있나能知道下一步吗고쳐 쓴 안내改写后的提示
1오류错误
2입력값이 올바르지 않습니다输入值不正确
3← 내 서비스가 보낼 실패 안내← 我的服务要发的失败提示
확인确认
  • 고쳐 쓴 안내에 사용자가 할 행동이 들어 있다. 「다시 …해 보세요」 같은 말이다.改写后的提示里有用户要做的动作,比如「请再…试一次」。
  • 서비스 쪽 문제일 때는 사용자 탓으로 돌리지 않았다.如果是服务端的问题,没有把责任推给用户。
6. 수업 범위6. 课程范围10-1

하나의 Next.js 프로젝트 안에서 연결한다在一个 Next.js 项目内连接 핵심核心

화면입력·버튼·결과画面输入·按钮·结果
↕
내부 API요청 처리와 응답内部 API处理请求并响应
↕
11회의 SQLite아직은 연결하지 않음第 11 次课的 SQLite今天还不连接
API는 외부 서비스만을 뜻하지 않습니다API 不只是外部服务

오늘은 자신의 서비스 안에서 화면과 기능을 연결하는 내부 API를 만듭니다.今天要做的是在自己服务内连接画面与功能的内部 API。

7. 약속표7. 约定表10-1

내 서비스의 핵심 API를 말로 정리한다用语言整理我的核心 API 실습实践

주소와 방법은 AI 제안 후에 적어도 됩니다. 먼저 사용자 행동, 보낼 데이터와 받을 데이터를 자신의 말로 적습니다.地址与方法可在 AI 提议后填写。先用自己的话写用户行动、发送与接收的数据。

세부 기술 설계는 평가 범위가 아닙니다技术细节不在评价范围

학생은 자신의 흐름에 필요한 요청과 응답의 의미를 설명하면 됩니다.学生只需要说明自己流程中请求与响应的意义。

8. DB로 이어지기8. 连到 DB10-1

API가 작동해도 아직 기억하지는 못한다API 能运行,但还不能记住 핵심核心

10회화면 ↔ API第 10 次课画面 ↔ API
▼
현재의 한계다시 열면 기록이 사라질 수 있다当前局限重新打开后记录可能消失
▼
11회화면 ↔ API ↔ SQLite第 11 次课画面 ↔ API ↔ SQLite

11회에는 새 프로젝트를 만드는 것이 아니라, 오늘의 요청·응답에 SQLite 저장과 조회를 덧붙입니다.第 11 次课不是重做项目,而是在今天的请求·响应中加上 SQLite 保存与查询。

오늘 확인할 한계今天要确认的局限

핵심 기능을 실행한 뒤 페이지를 새로 열거나 프로젝트를 다시 시작해 보세요. 무엇이 사라지는지가 11회의 출발점입니다.执行核心功能后重新打开页面或重启项目。消失的内容就是第 11 次课的起点。

9. 확인9. 确认10-1

확인 문제检查题

API를 “약속된 창구”라고 하는 이유는 무엇인가?为什么把 API 叫作“约定好的窗口”?
해설 보기查看解析

보내는 쪽과 받는 쪽이 무엇을 어디로 보내고 무엇을 돌려받을지 미리 정해 두었기 때문입니다. 약속이 없으면 화면은 무엇을 보낼지 모르고, 기능은 무엇을 돌려줄지 모릅니다.因为发送方与接收方事先约好了往哪里发什么、又会收到什么。没有约定,画面不知道该发什么,功能也不知道该回什么。

창구라는 말은 정해진 자리라는 뜻입니다. 아무 데나 말을 걸 수 없고 정해진 주소로만 요청합니다.“窗口”指的是固定的位置。不能随便找地方说话,只能往约定的地址发请求。

GET과 POST를 어떻게 구분할 수 있는가?怎样区分 GET 与 POST?
해설 보기查看解析

요청의 의도로 구분합니다. 이미 있는 정보를 보여 달라면 GET, 데이터를 보낼 테니 처리해 달라면 POST입니다.按请求的意图来分。要看已有的信息用 GET,发数据过去让它处理用 POST。

“내 기록을 보여 줘”는 GET, “오늘 읽은 책을 기록해 줘”는 POST입니다. 이름을 외우는 것이 아니라 둘 중 어느 쪽인지 판단하면 됩니다.“给我看我的记录”是 GET,“把今天读的书记下来”是 POST。不是背名字,而是判断属于哪一种。

요청과 응답에서 JSON은 어떤 역할을 하는가?JSON 在请求与响应中起什么作用?
해설 보기查看解析

오가는 데이터를 이름과 값의 쌍으로 담는 그릇입니다. task라는 이름 옆에 값이 있으면, 받는 쪽은 그것이 할 일의 내용임을 알 수 있습니다.它是把往返数据装成名称与值成对的容器。看到 task 这个名字旁边的值,接收方就知道那是待办的内容。

괄호와 쉼표를 외울 필요는 없습니다. AI가 만든 요청·응답에서 어떤 이름에 어떤 값이 들어 있는지 읽으면 됩니다.不必背括号和逗号。只要能在 AI 写出的请求与响应里读出哪个名字装着哪个值就行。

9. 확인9. 确认10-1

확인 문제检查题(이어서)(续)

실패 응답에 사용자가 다시 시도할 정보가 필요한 이유는 무엇인가?失败的响应里为什么要有让用户重试的信息?
해설 보기查看解析

실패했다는 사실만 알려 주면 사용자가 거기서 멈추기 때문입니다. 무엇이 잘못됐고 어떻게 고치는지 알아야 정상 흐름으로 돌아갈 수 있습니다.只告诉他失败了,用户就停在那里了。要知道哪里错了、怎么改,才回得到正常流程。

“오류”보다 “할 일을 한 글자 이상 입력한 뒤 다시 추가해 보세요”가 좋은 응답입니다. 서비스 쪽 문제라면 사용자 탓으로 돌리지 않고 다시 시도할 수 있다고 알려 줍니다.比起“错误”,“请输入至少一个字后再添加”才是好响应。若是服务本身的问题,就不要归咎用户,告诉他可以再试一次。

10회의 API와 11회의 DB는 어떻게 연결되는가?第 10 次课的 API 与第 11 次课的数据库怎样连起来?
해설 보기查看解析

11회에 새 프로젝트를 만드는 것이 아니라, 오늘 만든 요청·응답에 SQLite 저장과 조회를 덧붙입니다. 화면 ↔ API가 화면 ↔ API ↔ SQLite가 됩니다.第 11 次课不是另做一个项目,而是在今天做好的请求·响应上加进 SQLite 的保存与查询。画面 ↔ API 变成画面 ↔ API ↔ SQLite。

그래서 오늘 다시 열었을 때 무엇이 사라지는지 확인해 두는 것이 11회의 출발점이 됩니다.所以今天确认重新打开后什么不见了,就成了第 11 次课的起点。

자기 말로 설명하기用自己的话说

“내 서비스에서 사용자가 ______을 하면 화면은 ______을 보내고, 돌아온 ______을 화면에 보여 준다.” 세 빈칸을 채워 보세요.“在我的服务里,用户做了 ______,画面就发送 ______,再把收到的 ______ 显示出来。”请填这三个空。

10. 정리10. 小结10-1

핵심 정리와 완료 확인核心小结与完成确认

이번 차시에서 남길 것本课时要记住的
  • API는 화면과 기능 사이의 약속된 창구다.API 是画面与功能之间约定好的窗口。
  • 학생은 보낼 데이터와 받을 데이터를 설명하면 된다.学生能说明要发送与接收的数据即可。
  • 11회에 오늘의 API에 SQLite를 연결한다.第 11 次课会在今天的 API 上连接 SQLite。
다음 차시로进入下一课时

AI가 코드를 수정하기 전에 요청·응답·화면 변화를 먼저 설명하게 하고, 약속표와 맞을 때만 핵심 API 하나를 연결합니다.让 AI 在改代码前先说明请求、响应与画面变化,只有与约定表一致时才连接一个核心 API。