Linux Command Line & Bash Scripting Mastery · 강의

curl과 jq를 함께 사용한 REST API 활용

curl 요청을 jq로 연결하여 스크립트에서 실시간 API 응답을 추출하고 페이지 단위로 조회하며 형식을 변환합니다.

레슨 3/413개 단계

curl과 jq를 함께 사용한 REST API 활용은(는) CoddyKit의 무료 Linux Command Line & Bash Scripting Mastery 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Linux Command Line & Bash Scripting Mastery 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Linux Command Line & Bash Scripting Mastery 강의에는 총 4개의 강의가 포함되어 있습니다.

curl + jq가 강력한 조합인 이유

REST API는 JSON을 반환합니다. curl은 원시 응답을 가져오고, jq는 이를 잘라 내고 필터링하고 재구성합니다. 이 모든 작업을 하나의 파이프라인에서 수행할 수 있으므로 Python 스크립트, Postman, 중간 파일이 필요하지 않습니다.

  • curl은 HTTP를 처리합니다. 메서드, 헤더, 인증, 리디렉션 등이 이에 해당합니다.
  • jq는 JSON을 처리합니다. 필터링, 매핑, 변환, 서식 지정 등이 이에 해당합니다.
  • 두 도구를 파이프로 연결하면 간결하고 조합 가능한 API 작업 흐름을 만들 수 있습니다.

이 강의에서는 기본 원리부터 실제 페이지 매김과 스크립트 패턴까지 이 기술을 단계적으로 익힙니다.

jq로 연결하는 기본 curl 파이프라인

가장 간단한 패턴은 curl의 출력을 jq로 직접 전달하는 것입니다. -s(자동 표시 안 함)를 사용하면 curl의 진행률 표시가 나타나지 않아 JSON 본문만 jq에 전달됩니다.

  • -s — 자동 표시 안 함 모드, 진행률 표시줄을 표시하지 않습니다.
  • . — jq의 항등 필터로, 전체 응답을 보기 좋게 출력합니다.
  • jq의 -r — 원시 출력(문자열을 감싸는 따옴표를 표시하지 않음)입니다.
#!/usr/bin/env bash
# Fetch a public endpoint and pretty-print the JSON
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq '.'

# Extract just the title field as a plain string
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq -r '.title'

요청 헤더 설정 및 인증 토큰 전달

대부분의 운영 API에는 Authorization 헤더나 API 키가 필요합니다. -H로 헤더를 전달하고 비밀 값은 환경 변수에 저장하세요. 비밀 값을 코드에 직접 입력해서는 안 됩니다.

  • -H 'Authorization: Bearer $TOKEN' — 인증 헤더를 주입합니다.
  • -H 'Accept: application/json' — JSON을 응답으로 명시적으로 요청합니다.
  • 변수는 큰따옴표 안에서 확장되므로 헤더 문자열을 "로 감싸세요.
#!/usr/bin/env bash
TOKEN="${GITHUB_TOKEN}"   # set in your shell environment
USER="octocat"

curl -s \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/users/${USER}" \
| jq '{login: .login, repos: .public_repos, followers: .followers}'

배열 필터링 — .[] 및 select()

API는 배열을 반환하는 경우가 많습니다. .[]를 사용하여 모든 요소를 순회한 다음 select()로 조건에 맞는 항목만 남기세요.

  • .[] — 배열을 객체 스트림으로 펼칩니다.
  • select(.field == value) — 일치하는 객체만 남깁니다.
  • |로 여러 필터를 연결할 수 있습니다.
#!/usr/bin/env bash
# Fetch all todos and keep only the completed ones
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true) | {id, title}]'

# Count how many are completed
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true)] | length'

map()으로 여러 필드 추출하기

map()은 배열의 모든 요소에 변환을 적용하고 새 배열을 반환합니다. 이는 [.[] | ...]과 같지만 더 읽기 쉽습니다.

  • map({key: .field}) — 모든 객체의 구조를 바꿉니다.
  • @csv 또는 @tsv와 결합하여 표 형식의 출력을 생성합니다.
  • @csv/@tsv와 함께 -r을 사용하면 원시 텍스트(JSON 인용 없음)를 얻을 수 있습니다.
#!/usr/bin/env bash
# Reshape a posts list into id + title pairs
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq 'map({id, title: .title[0:40]})'

# Output as CSV for import into a spreadsheet
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq -r '.[] | [.id, .userId, .title] | @csv'

페이지가 빌 때까지 반복하는 페이지 매김 패턴

대부분의 API는 결과를 여러 페이지로 나눕니다. 일반적인 패턴은 페이지 카운터를 증가시키고 반환된 배열이 비어 있으면 중지하는 while 반복문입니다.

  • $(curl ...)을 사용하여 curl 응답을 변수에 저장합니다.
  • jq 'length'를 사용하여 해당 페이지에 항목이 있는지 확인합니다.
  • jq -s(슬러프)를 사용하거나 파일에 추가하여 결과를 누적합니다.
#!/usr/bin/env bash
# Paginate through jsonplaceholder posts (simulated: page stops at page 2
# because the API returns the full list regardless of ?_page, but the
# pattern is correct for real paginated APIs)

PAGE=1
PER_PAGE=10
OUTPUT="all_posts.json"
echo '[]' > "$OUTPUT"

while true; do
  RESPONSE=$(curl -s "https://jsonplaceholder.typicode.com/posts?_page=${PAGE}&_limit=${PER_PAGE}")
  COUNT=$(echo "$RESPONSE" | jq 'length')

  if [ "$COUNT" -eq 0 ]; then
    echo "No more pages. Stopping at page $((PAGE - 1))."
    break
  fi

  # Merge new items into the accumulated JSON array
  CURRENT=$(cat "$OUTPUT")
  echo "$CURRENT" "$RESPONSE" | jq -s '.[0] + .[1]' > "$OUTPUT"
  echo "Page $PAGE: fetched $COUNT items."
  PAGE=$((PAGE + 1))
done

echo "Total collected: $(jq 'length' "$OUTPUT")"

Link 헤더 페이지 매김(GitHub 방식)

GitHub와 많은 다른 API는 다음 페이지의 URL을 제공하기 위해 Link 응답 헤더를 사용합니다. URL을 추측하지 말고 헤더를 구문 분석해야 합니다.

  • curl -i는 응답 헤더를 표준 출력에 포함합니다. 또는 -D -를 사용하여 헤더를 표준 출력으로 내보낼 수 있습니다.
  • grep과 sed를 사용하여 Link: <url>; rel="next" 헤더를 구문 분석합니다.
  • rel="next" 링크가 더 이상 없을 때까지 반복합니다.
#!/usr/bin/env bash
# Follow Link-header pagination (GitHub repos example)
# Requires GITHUB_TOKEN in environment
TOKEN="${GITHUB_TOKEN}"
NEXT_URL="https://api.github.com/users/torvalds/repos?per_page=5"
ALL_REPOS="[]"

while [ -n "$NEXT_URL" ]; do
  # Capture full response (headers + body) to a temp file
  TMPFILE=$(mktemp)
  curl -sD "$TMPFILE" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "$NEXT_URL" \
  | {
      BODY=$(cat)
      ALL_REPOS=$(echo "$ALL_REPOS" "$BODY" | jq -s '.[0] + .[1]')
      echo "$ALL_REPOS" > /tmp/repos_acc.json
    }

  # Extract next URL from Link header
  NEXT_URL=$(grep -i '^link:' "$TMPFILE" \
    | sed -E 's/.*<([^>]+)>; rel="next".*/\1/;t;d')
  rm -f "$TMPFILE"
done

echo "Total repos: $(jq 'length' /tmp/repos_acc.json)"

요청 연결하기 — 한 호출의 출력을 다른 호출의 입력으로 사용하기

일반적인 작업 흐름은 목록을 가져오고, ID를 추출한 다음, 각 ID의 세부 정보를 가져오는 것입니다. $() 명령 치환으로 중간 값을 저장하고 다음 URL에 전달합니다.

  • jq -r '.field'를 사용하여 단일 값을 추출합니다.
  • while read 반복문 안에서 jq -r '.[].id'를 사용하여 여러 ID를 반복 처리합니다.
  • 요청 사이에 sleep을 사용하여 요청 속도 제한을 준수합니다.
#!/usr/bin/env bash
# Step 1: get all user IDs from the /users endpoint
# Step 2: for each user, fetch their posts and count them

curl -s 'https://jsonplaceholder.typicode.com/users' \
| jq -r '.[].id' \
| while read -r USER_ID; do
    POST_COUNT=$(curl -s "https://jsonplaceholder.typicode.com/posts?userId=${USER_ID}" \
                 | jq 'length')
    echo "User ${USER_ID}: ${POST_COUNT} posts"
    sleep 0.1   # be polite to the API
done

POST 요청 — JSON 페이로드 보내기

리소스를 생성하거나 업데이트하려면 JSON 본문과 함께 POST 또는 PUT을 보냅니다. 본문에는 -X POST, -H 'Content-Type: application/json', -d를 사용합니다. 인용 부호 처리 문제를 피하려면 jq -n으로 페이로드를 구성합니다.

  • jq -n --arg key value '{key: $key}' — jq에서 변수를 안전하게 보간합니다.
  • 구성한 JSON을 curl의 -d @-로 직접 파이프하여 표준 입력에서 본문을 읽게 합니다.
  • 다른 jq 필터로 응답을 즉시 구문 분석합니다.
#!/usr/bin/env bash
TITLE="My New Post"
BODY_TEXT="Written via curl and jq."
USER_ID=1

# Build the JSON payload safely and POST it
RESPONSE=$(jq -n \
  --arg title   "$TITLE" \
  --arg body    "$BODY_TEXT" \
  --argjson userId "$USER_ID" \
  '{title: $title, body: $body, userId: $userId}' \
| curl -s \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    'https://jsonplaceholder.typicode.com/posts')

echo "Created post ID: $(echo "$RESPONSE" | jq '.id')"
echo "Full response:"
echo "$RESPONSE" | jq '.'

오류 처리 — HTTP 상태 코드와 API 오류

HTTP 연결에 성공했다고 해서 API 호출에도 성공한 것은 아닙니다. HTTP 상태 코드와 JSON 오류 필드를 별도로 확인해야 합니다.

  • curl -w '%{http_code}'는 상태 코드를 표준 출력에 덧붙입니다. -o를 사용하면 본문을 파일에 기록할 수 있습니다.
  • 스크립트에서 코드를 비교하고 4xx와 5xx를 서로 다르게 처리합니다.
  • 많은 API는 본문에 {"error": "..."}를 포함합니다. jq의 has() 또는 type으로 확인합니다.
#!/usr/bin/env bash
API_URL='https://jsonplaceholder.typicode.com/todos/99999'
TMPBODY=$(mktemp)

HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' "$API_URL")

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
  echo "Success ($HTTP_CODE):"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -eq 404 ]; then
  echo "Resource not found (404). Body:"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -ge 500 ]; then
  echo "Server error ($HTTP_CODE). Retrying later."
else
  echo "Unexpected status: $HTTP_CODE"
  cat "$TMPBODY"
fi

rm -f "$TMPBODY"

재사용 가능한 API 도우미 함수 만들기

curl과 오류 확인에 필요한 반복 코드를 셸 함수로 묶습니다. 이 함수가 인증, 상태 확인, JSON 추출을 처리하므로 호출자는 엔드포인트와 jq 필터만 전달하면 됩니다.

  • HTTP 오류가 발생하면 0이 아닌 종료 코드를 반환하여 호출자가 || 또는 set -e를 사용할 수 있게 합니다.
  • jq 필터를 인수로 받아 하나의 함수로 여러 엔드포인트를 처리합니다.
  • API가 필요한 모든 스크립트에서 이 함수 파일을 소스로 불러옵니다.
#!/usr/bin/env bash
# api_get <endpoint_path> <jq_filter>
# Returns filtered JSON or exits non-zero on error.
api_get() {
  local PATH_PART="$1"
  local JQ_FILTER="${2:-.}"
  local BASE_URL='https://jsonplaceholder.typicode.com'
  local TMPBODY
  TMPBODY=$(mktemp)

  local HTTP_CODE
  HTTP_CODE=$(curl -s \
    -o "$TMPBODY" \
    -w '%{http_code}' \
    "${BASE_URL}${PATH_PART}")

  if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
    echo "[ERROR] HTTP $HTTP_CODE for ${PATH_PART}" >&2
    rm -f "$TMPBODY"
    return 1
  fi

  jq -r "$JQ_FILTER" "$TMPBODY"
  rm -f "$TMPBODY"
}

# Usage examples
api_get '/todos/1' '.title'
api_get '/posts?userId=1' '[.[] | .title]'
api_get '/users' '.[] | "\(.id) \(.name) <\(.email)>"'

지식 확인: 페이지 매김 전략

curl과 jq를 사용하여 Bash 스크립트에서 페이지로 나뉜 REST API 응답을 처리하는 방법을 얼마나 이해했는지 확인해 보세요.

레슨 요약: curl + jq API 스크립팅

이제 Bash 명령줄에서 REST API를 사용하기 위한 완전한 도구 모음을 갖추었습니다.

  • 기본 파이프라인: curl -s URL | jq 'filter' — 모든 작업의 기반입니다.
  • 인증 헤더: 환경 변수의 토큰을 -H를 통해 전달하고, 코드에 직접 작성하지 않습니다.
  • 배열 처리: .[], select(), map()으로 API 응답을 잘라내고 구조를 바꿉니다.
  • 페이지 매김: 페이지 카운터(빈 배열 표시값)를 사용하여 반복하거나, 다음 URL 방식 API에서는 Link 헤더를 구문 분석합니다.
  • 연결: 한 응답에서 ID를 추출하고 while read 반복문 안에서 다음 요청에 전달합니다.
  • 안전한 페이로드를 사용하는 POST: jq -n --arg로 JSON 본문을 만들고 curl의 -d @-로 파이프합니다.
  • 오류 처리: HTTP 상태(-w '%{http_code}')와 본문에 포함된 API 수준 오류를 분리합니다.
  • 재사용 가능한 도우미: 반복 코드를 셸 함수로 묶어 스크립트를 간결하게 유지하고 DRY 원칙을 지킵니다.

이러한 패턴을 결합하면 추가 런타임 없이 셸에서 모든 JSON API 작업 흐름을 자동화할 수 있습니다.

무료로 시작

AI 튜터와 함께 Bash을(를) 배우세요 — 무료

브라우저에서 실제 코드를 작성하고 실행하며, 24/7 AI 튜터로부터 즉각적인 도움을 받고, 웹이나 앱에서 중단한 부분부터 계속 학습하세요.

코스
22
레슨
88

자주 묻는 질문

“curl과 jq를 함께 사용한 REST API 활용” 강의는 무료인가요?

네 — “curl과 jq를 함께 사용한 REST API 활용” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Linux Command Line & Bash Scripting Mastery 강의 전체를 잠금 해제할 수 있습니다. Linux Command Line & Bash Scripting Mastery 강의에는 총 4개의 강의가 포함되어 있습니다.

“curl과 jq를 함께 사용한 REST API 활용”에서 뭘 배우나요?

curl 요청을 jq로 연결하여 스크립트에서 실시간 API 응답을 추출하고 페이지 단위로 조회하며 형식을 변환합니다. 브라우저에서 직접 실행하는 실습 코드로 Linux Command Line & Bash Scripting Mastery을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Linux Command Line & Bash Scripting Mastery을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Linux Command Line & Bash Scripting Mastery은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.

“curl과 jq를 함께 사용한 REST API 활용” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Linux Command Line & Bash Scripting Mastery 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Linux Command Line & Bash Scripting Mastery 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. jq 파이프라인으로 JSON 필터링 및 선택
  2. jq로 JSON 객체 변환 및 생성
  3. curl과 jq를 함께 사용한 REST API 활용
  4. yq로 YAML 구성 파일 편집
← Linux Command Line & Bash Scripting Mastery(으)로 돌아가기