# REST로 업무를 걸어보기
> **이 장에서 배우는 것**
> 읽는 장이 아니라 **하는 장**입니다. 업무 하나를 REST로 걸고, 진행을 읽고,
> **일부러 두 번 보내** 무엇이 벌어지는지 확인합니다.
## 준비물
```
□ 40분
□ 켜져 있는 HyperTeams와 등록된 작업 폴더 하나
□ curl 또는 아무 HTTP 클라이언트
□ 토큰
□ 되돌리기 쉬운 폴더로 시작하세요
```
토큰을 아직 안 받았다면 [REST로 업무 시키기](/guide/ht-rest-api)에
발급 절차가 있습니다.
**토큰을 대화창이나 이슈에 붙여넣지 마세요.** 이 실습 내내 터미널 밖으로 나가지
않게 두세요.
---
## 1단계 — 읽기부터 (5분)
**업무를 만들기 전에** 조회가 되는지부터 확인합니다. 인증이 틀렸는지 요청이
틀렸는지를 나중에 헷갈리지 않기 위해서입니다.
```
□ 목록 조회를 한 번 호출했다
□ 200 이 돌아왔다
□ 401/403 이면 → 토큰 문제입니다. 여기서 해결하고 다음으로
```
**여기서 막히면 2단계로 가지 마세요.** 인증 문제를 안고 업무 생성으로 넘어가면
원인이 두 개가 됩니다.
---
## 2단계 — 읽기만 하는 업무 걸기 (10분)
첫 업무는 **파일을 안 고치는 것**으로.
```
지시 예:
"이 폴더에서 테스트가 없는 파일 목록을 뽑아주세요. 파일은 수정하지 마세요."
```
### 무엇을 보나
```
□ 응답에 업무 id 가 들어 있나
□ 그 id 로 진행 상황을 조회할 수 있나
□ 화면(대시보드)에도 같은 업무가 보이나 ← 두 표면이 같은 것을 본다는 확인
```
**세 번째가 중요합니다.** REST와 화면이 **같은 업무**를 보고 있다는 것을 눈으로
확인해두면, 나중에 "코드로 건 건 어디서 보나요"를 겪지 않습니다.
---
## 3단계 — 진행 읽기 (5분)
같은 업무를 **끝날 때까지 몇 번 조회**하세요.
| 확인 | |
|---|---|
| 상태 값이 바뀌는가 | □ |
| 끝났을 때 결과를 어디서 읽나 | □ |
| 실패했다면 이유가 응답에 들어 있나 | □ |
```
□ 조회를 몇 초 간격으로 했나 — 적어두세요
```
**마지막 줄을 적어두세요.** 나중에 자동화할 때 이 간격이 그대로 설계값이 됩니다.
너무 자주 부르면 부하만 늘고, 너무 뜸하면 반응이 느려집니다.
---
## 4단계 — 일부러 두 번 보내기 (15분)
**이게 이 실습의 핵심입니다.** 같은 요청을 **연달아 두 번** 보내세요.
```
□ 같은 본문으로 두 번 호출했다
```
### 무엇을 보나
| 벌어진 일 | 뜻 |
|---|---|
| 업무가 두 개 생김 | **정상입니다. 그리고 그게 문제입니다** |
| 하나만 생김 | 어딘가에서 막아준 것 — 무엇이 막았는지 확인하세요 |
**[멱등 키가 없습니다](/guide/ht-rest-api).** 즉 **두 번 보내면 두 번
실행됩니다.** 읽기 업무라 지금은 무해했지만, 이게 메일 발송이었다면 두 통이
나갑니다.
### 그래서 무엇을 해야 하나
호출하는 쪽에서 막아야 합니다. 지금 우리 상황에 맞는 것을 고르세요.
```
□ 보내기 전에 "같은 지시의 진행 중 업무가 있나" 조회로 확인한다
□ 우리 쪽에서 요청 키를 만들어 이미 보낸 키는 다시 안 보낸다
□ 재시도는 실패가 확인됐을 때만 한다 ← 타임아웃은 실패가 아닙니다
```
**세 번째 줄이 가장 자주 사고를 냅니다.** 응답이 늦으면 실패로 보고 다시
보내는데, 서버는 첫 요청도 정상 처리 중입니다.
---
## 5단계 — 정리 (5분)
```
□ 연습으로 만든 업무를 정리했다
□ 토큰이 기록에 남지 않았는지 확인했다 (쉘 히스토리 포함)
□ 조회 간격과 중복 방지 방법을 한 줄로 적어뒀다
```
---
## 자기 점검
```
□ 읽기 호출로 인증을 먼저 확인했다
□ REST와 화면이 같은 업무를 본다는 것을 확인했다
□ 같은 요청을 두 번 보내 업무가 두 개 생기는 것을 봤다 ← 안 했으면 4단계로
□ 중복을 막을 방법을 하나 골랐다
```
---
## 확인
**1. 업무를 만들기 전에 조회부터 호출해보라는 이유는?**
답
**인증 문제와 요청 문제를 분리하기 위해서**입니다. 조회가 되면 토큰은 정상이라는
뜻이라, 이후 오류는 요청 내용 쪽만 보면 됩니다.
**2. 같은 요청을 두 번 보내면 왜 업무가 두 개 생깁니까?**
답
**멱등 키가 없기 때문**입니다. 서버는 두 요청을 별개로 봅니다. 중복 방지는
호출하는 쪽에서 해야 합니다.
**3. 타임아웃을 실패로 보고 재시도하면 무엇이 문제입니까?**
답
**타임아웃은 실패가 아니라 응답이 늦은 것**일 수 있습니다. 서버가 첫 요청을 정상
처리하는 중에 두 번째가 들어오면 같은 일이 두 번 실행됩니다.
---
이제 모델 쪽 문을 엽니다 → [모델 갖추기 — 내려받고 띄우기](/guide/ht-local-models)