클라이언트 라이브러리

REST API는 평범한 HTTP와 JSON이므로 fetch 호출만으로도 충분히 잘 쓸 수 있습니다. 클라이언트 라이브러리는 아무도 두 번은 쓰고 싶지 않은 부분을 위해 존재합니다. 요청 제한에 걸린 요청을 올바르게 재시도하는 일, 재시도한 생성 요청을 안전하게 만드는 일, 커서를 따라 목록 끝까지 훑는 일입니다.

라이브러리는 셋이지만 규약은 하나입니다.

| 언어 | 패키지 | 소스 | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

설치

아직 패키지는 npm, PyPI, Packagist에 올라가 있지 않습니다. 배포는 레지스트리 계정이 준비되기를 기다리는 중입니다. 코드 자체는 완성되어 있어 지금도 저장소를 내려받아 설치할 수 있으며, 계정이 마련되면 아래 명령은 npm install @linkprofit/sdk 한 줄(그리고 각 언어의 대응 명령)로 바뀝니다.

Node는 로컬에 내려받은 소스에서 설치합니다.

npm install /path/to/linkprofit/packages/sdk-node

Python도 로컬에 내려받은 소스에서 설치합니다.

pip install /path/to/linkprofit/sdk/python

PHP는 composer.json에 Composer 경로 저장소를 지정해 설치합니다.

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

세 라이브러리가 똑같이 하는 일

이 라이브러리들은 일부러 밋밋하게, 그리고 일부러 서로 닮게 만들었습니다. 동작을 한 번 익혀 두면 어느 언어에서든 그대로 통합니다.

인증. 워크스페이스 키(lp_live_…)를 넘기면 클라이언트가 모든 요청에 Authorization 헤더를 붙입니다. 기본 URL은 옵션이므로 테스트에서는 같은 코드를 로컬 인스턴스에 그대로 쓸 수 있습니다. 스코프와 키 교체는 인증 방식을 참고하십시오.

서버를 존중하는 재시도. 429나 일시적인 5xx는 대기 시간을 늘려 가며 재시도하고, 대기 시간은 짐작하는 대신 Retry-After를 그대로 따릅니다. 윈도가 언제 다시 열리는지는 서버가 이미 알고 있기 때문입니다. 시도 횟수에는 상한이 있으며, 요청 자체가 잘못되어 실패한 경우(validation_failed, conflict, not_found)에는 절대 재시도하지 않습니다. 잘못된 요청을 반복해 봐야 요청 제한 예산만 축낼 뿐입니다.

멱등하게 처리되는 변경 요청. 데이터를 변경하는 호출에는 모두 Idempotency-Key가 담기므로, 네트워크 시간 초과 뒤에 재시도해도 링크가 하나 더 만들어지는 대신 저장해 둔 응답이 반환됩니다. 재시도가 다른 프로세스나 나중의 실행에서 올 수 있다면 주문 id나 작업 id처럼 직접 정한 키를 넘겨도 됩니다. 키는 24시간 동안 저장되며, 같은 키를 다른 본문과 함께 보내면 409가 반환됩니다.

반복자로 다루는 커서 페이지네이션. 목록 엔드포인트는 커서 방식으로 페이지를 나누며, 클라이언트는 이를 반복자로 노출합니다. 여러분은 링크를 순회하기만 하면 되고, 현재 페이지가 소진되면 클라이언트가 다음 페이지를 가져오며 커서가 null이 되면 멈춥니다. 페이지 번호를 계산할 일도, 한 칸 어긋난 계산이 조용히 한 건을 빠뜨릴 위험도 없습니다.

예외로 전달되는 오류. 실패는 각 언어에서 자연스러운 오류 타입으로 발생하며, API의 code와 사람이 읽는 메시지, 검증 실패라면 필드별 details까지 함께 담습니다. 메시지 문구가 아니라 코드로 분기하십시오. 문서로 약속된 규약은 코드 쪽입니다.

Node 클라이언트의 요청과 응답 타입은 레퍼런스가 렌더링하는 것과 같은 OpenAPI 문서에서 생성되며, 그 문서는 /openapi.json에 공개되어 있습니다. 그래서 타입이 실제로 동작하는 API와 어긋날 수 없습니다. Python과 PHP 클라이언트는 같은 문서를 각 언어의 관용에 맞춰 사람이 직접 따릅니다.

빠른 시작

각 패키지에는 기능 전체를 설명하는 README가 함께 들어 있습니다. 아래 예제는 세 라이브러리가 공유하는 형태를 보여 줍니다. 키로 클라이언트를 만들고, 리소스 그룹을 호출하고, 타입이 지정된 객체를 돌려받는 흐름입니다.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

어느 것을 골라야 할까요

• Node / TypeScript — 타입이 OpenAPI 문서에서 곧바로 나오기 때문에 다루는 범위가 가장 넓습니다. JavaScript 백엔드나 서버리스 함수, 빌드 스크립트에는 자연스러운 선택입니다.
• Python — 리포팅과 데이터 작업용입니다. 분석 데이터를 노트북이나 예약 작업, 대시보드 피드로 끌어옵니다.
• PHP — CMS 쪽 세계를 위한 것입니다. 콘텐츠를 게시할 때 링크를 단축하는 WordPress 플러그인이나 Laravel 서비스가 여기에 해당합니다.
• 아무것도 쓰지 않기 — 쓰는 언어가 이 셋 밖에 있다면, API는 그저 평범한 HTTP입니다. 빠른 시작은 curl을 앞세워 쓰여 있고, 클라이언트가 하는 일(재시도, 멱등 처리, 커서)은 모두 문서로 공개된 동작이라 쉰 줄이면 직접 구현할 수 있습니다.

무엇을 고르든 엔드포인트와 필드, 오류 코드의 전체 목록은 API 레퍼런스에 있습니다. 라이브러리는 그 위에 얹은 편의 장치일 뿐, 결코 다른 API가 아닙니다.

함께 읽어 두면 좋은 글

• 요청 제한 — 재시도 로직이 그 안에서 움직이는 예산입니다.
• 웹훅 — 폴링하는 대신 이벤트를 밀어서 받습니다.
• MCP 서버 — 같은 작업을 AI 어시스턴트에서 수행합니다.