public-apis — 43만 스타
큐레이션 레포의 운영학

먼저, "Awesome 리스트"가 뭔가?

왜 이런 레포가 43만 스타를 받았나.

GitHub에는 Awesome List라고 부르는 큐레이션 레포 장르가 있다. "Awesome React", "Awesome Python", "Awesome Self-hosted" 같이 어떤 주제에 대해 좋은 자료·라이브러리·서비스 링크를 README 하나에 모아놓은 형태다. 누구나 PR을 보내 항목을 추가할 수 있고, 사이트도 DB도 없이 그냥 마크다운 파일 한 장이 전부다.

이 장르에서 단연 1위가 public-apis/public-apis다. 회원가입·결제 없이 누구나 호출할 수 있는 "공개 API" 1,400개 가까이를 카테고리별로 묶어놨다. 그런데 43만 스타라는 숫자는 단순히 "리스트가 길어서"가 아니다. 10년 넘게 죽지 않고 살아남은 운영 시스템이 진짜 자산이다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

43만 스타·트렌딩 76회 등장의 이유

2016년 첫 커밋 이후 10년, 어떻게 살아남았나.

경쟁 우위 — "품질을 강제하는 자동화"

비슷한 Awesome 리스트는 GitHub에 수천 개 있다. 대부분 첫 1~2년은 활발하다가 PR이 쌓이며 죽는다. 메인테이너 한두 명이 매일 들어오는 PR을 손으로 검토하다가 지쳐버리기 때문. public-apis가 살아남은 결정적 이유는 사람이 검토하기 전에 봇이 형식·중복·링크 작동 여부까지 다 검사한다는 점이다.

핵심 강점 5가지

• 형식 검증 자동화 — Python 스크립트(format.py)가 알파벳 순서·컬럼 개수·대소문자·설명 길이까지 체크
• 매일 링크 살아있는지 확인 — GitHub Actions 크론잡이 매일 00:00 UTC에 전 링크 검사
• 마케팅 PR 거부 정책 — 유료 API·자사 홍보용 PR은 CONTRIBUTING.md에 명시적으로 거부
• 카테고리당 최소 3개 강제 — 잡다한 카테고리 난립 방지
• 오직 README.md 한 파일 — 사이트도 DB도 없다. 모든 정보가 git에 평문, 영원히 사라지지 않는다

경쟁 비교 — 다른 카탈로그와의 위치

전체 기술 지도

코어 검증 도구 · CI/CD · 의존성.

놀랍게도 이 레포의 코드는 파이썬 ~550줄이 전부다. "API 리스트 레포"라기보다 "Awesome 리스트를 운영하는 최소 도구 모음"으로 봐야 한다.

코어 검증 도구 (Python ~550줄)

CI/CD — GitHub Actions 워크플로 3개

의존성 — 단 5개, 모두 버전 핀고정

certifi==2021.10.8            # SSL 인증서 번들
charset-normalizer==2.0.10    # 인코딩 자동 감지
idna==3.3                     # 국제화 도메인 처리
requests==2.27.1              # HTTP 클라이언트 (핵심)
urllib3==1.26.8               # requests의 내부 의존

인프라 비용 — 0원

시스템 구조와 4가지 설계 패턴

전체 흐름도 → 핵심 패턴 하나하나.

시스템 구조도 — PR이 들어와서 머지되기까지

┌────────────────────────────────────────────────────────────────┐
│                       외부 컨트리뷰터                            │
│                          (전 세계)                              │
└───────────────┬────────────────────────────────────────────────┘
                │ Fork → README 수정 → PR 생성
                ▼
┌────────────────────────────────────────────────────────────────┐
│                    GitHub 저장소 (master)                       │
│                                                                │
│   README.md (203 KB, 1,400+ APIs, 50+ 카테고리)                │
│                                                                │
└───────────────┬────────────────────────────────────────────────┘
                │ PR 생성 → 자동 트리거
                ▼
┌────────────────────────────────────────────────────────────────┐
│                 GitHub Actions Runner (Ubuntu)                  │
│                                                                │
│   ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│   │  format.py      │  │  links.py       │  │ test_pkg.yml │ │
│   │  형식 검사       │→ │  추가 링크 검증  │→ │ unittest     │ │
│   │  (정규식)        │  │  (HTTP 요청)    │  │              │ │
│   └─────────────────┘  └─────────────────┘  └──────────────┘ │
│                                                                │
└───────────────┬────────────────────────────────────────────────┘
                │ 모두 통과 시
                ▼
┌────────────────────────────────────────────────────────────────┐
│                   사람 리뷰어 (메인테이너)                       │
│                마케팅성 PR 차단, 분류 정정 등                    │
└───────────────┬────────────────────────────────────────────────┘
                │ 머지
                ▼
┌────────────────────────────────────────────────────────────────┐
│                매일 00:00 UTC: 전체 링크 검사                    │
│             (validate_links.yml — cron job)                   │
│            → 죽은 링크 발견 시 이슈로 자동 보고                  │
└────────────────────────────────────────────────────────────────┘

패턴 1 — "코드가 아닌 마크다운이 진실의 원천(SSOT)"

대부분의 큐레이션 사이트는 PostgreSQL DB + 어드민 패널을 만든다. public-apis는 README.md 자체가 DB다. 백업·검색·diff·history 모두 git이 처리한다. 43만 스타라는 트래픽에도 서버 비용이 0원. 사용자는 그냥 GitHub에서 텍스트 검색(Ctrl+F)으로 원하는 API를 찾는다.

패턴 2 — "PR 차분만 검증"으로 CI 비용 최소화

매번 1,400개 링크를 다 확인하면 GitHub Actions의 호출 한도와 외부 사이트 부담이 둘 다 폭증한다. 그래서 PR 단계에서는 github_pull_request.sh가 diff에서 + 라인만 추출해서 신규 링크만 검사한다.

# scripts/github_pull_request.sh 핵심 로직
curl -L "$DIFF_URL" -o diff.txt              # PR diff 다운로드
cat diff.txt | egrep "\+" > additions.txt    # 추가 라인만 추출
python scripts/validate/links.py additions.txt  # 새 링크만 검증

전체 검사는 매일 자정 cron으로 분리해 부하를 시간 축으로 분산했다. PR 응답은 빠르게, 전체 점검은 느리게 — 책임 분리가 깔끔하다.

패턴 3 — 정규표현식 기반 마크다운 파싱

format.py는 정규식 3개로 README 전체 구조를 파싱한다. Markdown 파서 라이브러리(markdown-it, mistune 등)를 쓰지 않는 이유는 "표가 정해진 형식인지" 자체가 검사 대상이라 관대한 파서로는 오류를 못 잡기 때문이다.

anchor_re = re.compile(anchor + r'\s(.+)')                 # ### 카테고리
category_title_in_index_re = re.compile(r'\*\s\[(.*)\]')   # 인덱스의 [카테고리]
link_re = re.compile(r'\[(.+)\]\((http.*)\)')              # [TITLE](URL)

에러 메시지는 줄 번호를 L003 형식으로 정렬해 출력한다 — IDE에서 바로 점프할 수 있게.

패턴 4 — Cloudflare 우회 휴리스틱

링크 검사 시 일부 사이트가 봇이라며 차단한다. 그래서 links.py는 가짜 User-Agent 4개를 무작위 회전하고, 403/503 응답을 받으면 Cloudflare 보호 페이지인지 17가지 마커로 판별해 "정상"으로 처리한다.

# links.py의 has_cloudflare_protection() 일부
cloudflare_flags = [
    '403 Forbidden', 'cloudflare', 'Security check',
    'Checking your browser before accessing',
    'DDoS protection by', 'Ray ID:', '_cf_chl', ...
]
if code in [403, 503] and server == 'cloudflare':
    if any(flag in resp.text for flag in cloudflare_flags):
        return True  # → 정상으로 간주, 오류 안 띄움

레포 구조 해부

어디에 뭐가 있는지.

public-apis/
├── README.md                    # 203KB, 모든 API 카탈로그 (이게 전부)
├── CONTRIBUTING.md              # 기여 규칙 — 마케팅 PR 거부 명시
├── LICENSE                      # MIT
├── .gitignore
├── .gitattributes
│
├── .github/
│   ├── ISSUE_TEMPLATE.md
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── assets/                  # 로고 이미지
│   └── workflows/
│       ├── test_of_push_and_pull.yml      # PR 검증
│       ├── test_of_validate_package.yml   # 스크립트 자체 테스트
│       └── validate_links.yml             # 매일 링크 검사 cron
│
└── scripts/
    ├── README.md                # 검증 스크립트 사용법
    ├── requirements.txt         # 5개 의존성 (버전 핀고정)
    ├── github_pull_request.sh   # PR diff 추출 후 검증
    ├── validate/                # 검증 패키지
    │   ├── __init__.py
    │   ├── format.py            # 형식 검증 (정규식 + 알파벳 정렬)
    │   └── links.py             # HTTP 요청으로 링크 검사
    └── tests/                   # 검증 스크립트의 단위 테스트
        ├── test_validate_format.py
        └── test_validate_links.py

분야별 배울 것

기술 영역마다 무엇을 가져갈지.

Python — 정규표현식과 텍스트 검증

GitHub Actions — 무료 CI/CD의 패턴

Bash — diff 가공 파이프라인

HTTP·requests — 가짜 봇 우회의 기술

오픈소스 운영 정책 — 가장 큰 교훈

시스템 요구사항

로컬에서 검증 돌릴 때의 최소 사양.

직접 해볼 수 있는 6단계

난이도별 실습 — Easy → Hard.

실습 1 — 검증 스크립트 로컬 실행Easy

실습 2 — 일부러 형식 오류 만들기Easy

실습 3 — links.py를 비동기로 개선Medium

실습 4 — 자신만의 큐레이션 레포 만들기Medium

실습 5 — 검색 API 만들기Hard

실습 6 — 죽은 링크 자동 PR 봇Hard

4주 심화 학습 로드맵

주차별로 따라가면 운영 자동화 마스터.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

레포 · 소스 · 학습 리소스.

공식 자료

• public-apis/public-apis (메인 레포)
• CONTRIBUTING.md — 기여 규칙
• scripts/validate/format.py 소스
• scripts/validate/links.py 소스
• .github/workflows — Actions 워크플로
• TrendShift 분석 — repositories/1677

관련 학습 리소스

• GitHub Actions 공식 문서
• Python requests 공식 문서
• regex101.com — 정규식 인터랙티브 테스터
• Python unittest 공식 문서
• Python re 모듈 공식 문서

유사·참고 큐레이션

• sindresorhus/awesome (Awesome 리스트의 원조)
• public-api-lists/public-api-lists (스핀오프 포크)
• RapidAPI Hub (상용 비교)
• APIs.guru (OpenAPI 컬렉션)