ETEAO
생산성

    도구 이름·설명·키워드로 검색하세요. ↑↓ 이동, Enter 열기, Esc 닫기.

    API 응답 목업(Mock) 생성기

    필드와 응답 형태를 골라 목업 API 응답 JSON 생성

    빠른 시작:
    리소스 필드

    API 응답 목업(Mock) 생성기 소개

    백엔드가 아직 없거나, 있어도 원하는 상태(빈 목록, 마지막 페이지, 422 오류)를 마음대로 만들기 어려울 때 프런트엔드는 가짜 응답으로 화면을 먼저 만듭니다. 이 도구는 필드 목록과 「봉투(envelope)」 모양을 고르면 그 모양대로 응답 JSON을 찍어 줍니다. 봉투는 순수 배열, data 래퍼, 페이지네이션(meta·links 포함), 단일 리소스, JSON:API, 오류 여섯 가지입니다.

    시드를 넣으면 mulberry32라는 작은 난수 생성기가 같은 순서로 값을 뽑아 매번 똑같은 응답이 나옵니다. 날짜 필드도 현재 시각이 아니라 2024-01-01(UTC)을 기준으로 그 이전 5년(2019~2023년) 안에서 만들기 때문에, 스냅샷 테스트에 넣어 두어도 내일 깨지지 않습니다. 과거로만 뽑으므로 가입일이 미래가 되지는 않지만, 「최근 7일」처럼 오늘 기준으로 거르는 화면에는 걸리는 데이터가 없다는 점은 알고 쓰세요.

    목업이 확인해 주는 것과 확인해 주지 못하는 것

    목업 응답으로 확인할 수 있는 것은 「내 화면이 이런 모양의 데이터를 받으면 제대로 그리는가」입니다. 스피너가 멈추는지, next가 null일 때 다음 버튼이 꺼지는지, 긴 이름이 줄바꿈되는지 같은 것들입니다.

    확인하지 못하는 것은 「실제 서버가 정말 이 모양으로 보내는가」입니다. 목업은 내가 상상한 API이고, 서버 팀이 필드 이름을 user_name에서 username으로 바꿔도 목업 기반 테스트는 계속 통과합니다. 이 간극을 메우는 방법이 계약 테스트(contract testing)입니다. Pact 문서는 이를 「각 애플리케이션을 따로 검사해, 주고받는 메시지가 『계약』에 적힌 공통 이해와 맞는지 확인하는 기법」이라고 설명합니다. 소비자(프런트) 테스트가 실행되면서 계약 파일이 만들어지고, 제공자(서버)는 그 계약을 자기 쪽에서 다시 돌려 봅니다.

    그래서 실무에서는 둘을 나눠 씁니다. 화면을 빨리 만들고 경계 상태를 재현할 때는 이런 목업, 배포 전에 서버와 어긋나지 않았는지 볼 때는 계약 테스트나 OpenAPI 스키마 검증입니다. 이 도구의 출력은 계약이 아니라 「그럴듯한 예시」라는 점을 팀 안에서 분명히 해 두면 혼선이 줄어듭니다.

    페이지네이션 숫자는 이렇게 계산된다

    total_pages는 total을 per_page로 나눠 올림한 값이고, 최소 1입니다. 현재 페이지에 실제로 들어가는 항목 수는 total − (page − 1) × per_page를 0과 per_page 사이로 자른 값입니다. id는 컬렉션 전체 순번이라 3페이지의 첫 항목은 21번부터 시작합니다. total을 0으로 두면 data가 빈 배열이고 total_pages는 1인 응답이 나오는데, 「결과 없음」 화면을 만들 때 쓰기 좋습니다.

    page를 total_pages보다 크게 넣으면 data가 비고 next가 null인 응답이 됩니다. 실제 API마다 이 경우를 빈 배열로 줄지 404로 줄지가 다르므로, 연결할 서버가 어느 쪽인지 먼저 확인해 두는 편이 좋습니다.

    오류 응답의 모양은 표준이 따로 있다

    이 도구의 오류 봉투는 { error: { status, code, message, request_id } } 형태이고, 422일 때는 details 배열이 붙습니다. 많은 API가 쓰는 관례적인 모양이지만 표준은 아닙니다. HTTP API 오류 형식의 표준은 RFC 9457(Problem Details)로, Content-Type을 application/problem+json으로 두고 type, title, status, detail, instance 멤버를 씁니다. type이 없으면 about:blank로 간주합니다. 연결할 서버가 RFC 9457을 따른다면 목업의 키 이름을 거기에 맞춰 바꿔서 쓰세요.

    상태 문구도 한 가지 알아 둘 점이 있습니다. 422의 이름은 RFC 9110에서 「Unprocessable Content」로 바뀌었고(예전 이름은 Unprocessable Entity), 이 도구는 새 이름을 출력합니다. 상태줄 문구(reason phrase)는 클라이언트가 해석하지 않아도 되는 부분이라, 서버가 예전 이름을 보내더라도 동작에는 영향이 없습니다. 오류 본문의 code 값(unprocessable_entity)은 API마다 정하는 관례 문자열이라 그대로 두었습니다.

    JSON:API 모드에서 달라지는 점

    JSON:API 모드는 각 레코드를 { type, id, attributes }로 감싸고, id 필드는 attributes에서 빠져 문자열로 올라갑니다. 규격이 리소스 id를 문자열로 요구하기 때문입니다. 최상위에는 jsonapi.version이 1.1로 들어가고 meta와 links가 붙습니다. relationships나 included는 만들지 않으므로, 관계 데이터를 다루는 화면은 이 부분을 직접 채워야 합니다.

    예시

    23개 중 3페이지(페이지당 10개), 시드 42

    입력
    스타일: 페이지네이션 / 필드: id(id), name(fullName), status(pick: active,pending) / total 23, page 3, per_page 10, resource users
    결과
    data 3건(id 21, 22, 23 — Noah Hernandez, Emma Jones, Michael Anderson), meta: {"page":3,"per_page":10,"total":23,"total_pages":3,"count":3}, links.prev: .../users?page=2&per_page=10, links.next: null

    23 ÷ 10을 올림하면 3페이지이고 마지막 페이지에는 3건만 남습니다. next가 null이므로 「다음」 버튼 비활성화를 확인하기 좋은 응답입니다. 같은 시드로 다시 만들면 이름까지 똑같이 나옵니다.

    422 오류 + HTTP 헤더 포함

    입력
    스타일: 오류 / 상태 코드 422 / HTTP 헤더 포함 켬 / 시드 7
    결과
    HTTP/1.1 422 Unprocessable Content Content-Type: application/json; charset=utf-8 ... {"error":{"status":422,"code":"unprocessable_entity","message":"The request was well-formed but contains semantic errors.","request_id":"9ed02560-...","details":[{"field":"id","issue":"is invalid"}]}}

    details의 field에는 스키마에서 id가 아닌 필드 하나가 시드에 따라 들어가고, issue는 타입에 맞는 문구가 됩니다(email이면 must be a valid email address). 이 예시처럼 필드가 id 하나뿐이면 id와 is invalid가 나옵니다. 오류 스타일에서는 상태 코드를 4xx·5xx만 고를 수 있습니다. 폼 오류를 필드 옆에 표시하는 화면이라면 field를 실제 입력 필드 이름으로 맞춰 쓰세요.

    사용 방법

    1. 리소스 필드를 추가하고 타입을 고릅니다. integer·float는 「최소,최대」, pick은 쉼표로 구분한 후보를 파라미터로 넣습니다.
    2. 응답 스타일과 total·page·per_page를 정합니다. 오류 스타일이면 상태 코드와 메시지를 고릅니다.
    3. 재현이 필요하면 시드를 넣고, 필요하면 HTTP 상태줄과 헤더 포함을 켭니다.
    4. 결과를 복사해 목 서버(MSW, json-server 등)나 테스트 픽스처 파일에 넣습니다.

    자주 묻는 질문

    목업만으로 테스트하면 충분한가요?

    화면 동작 확인에는 충분하지만 서버와의 호환성은 보장하지 않습니다. 서버 응답 형식이 바뀌어도 목업 테스트는 통과하므로, 배포 전에는 계약 테스트나 스키마 검증을 따로 두는 것이 안전합니다.

    204를 고르면 본문이 비어서 나오나요?

    네. RFC 9110상 204(와 304) 응답은 헤더 뒤 빈 줄에서 끝나므로, 어떤 스타일을 골랐든 본문을 만들지 않습니다. HTTP 헤더 포함을 켜면 상태줄과 헤더만(본문이 없으니 Content-Type도 빼고) 나오고, 끄면 출력이 비어 있습니다.

    avatar 필드의 이미지 주소는 어디서 오나요?

    i.pravatar.cc의 주소를 만듭니다. 외부 서비스라서 화면에 띄우면 그 서버로 요청이 나갑니다. 오프라인 테스트나 외부 요청이 막힌 CI에서는 로컬 이미지 경로로 바꾸세요.

    최대 몇 건까지 만들 수 있나요?

    total은 10,000, per_page는 1,000까지입니다. 페이지네이션 스타일에서는 현재 페이지의 항목만 실제로 생성됩니다.

    출처

    기준일:

    개인정보와 저장 방식

    관련 도구

    생산성