はじめに

Webサービスや社内ツールを作っていると、長いURLを自動的に短縮したい場面があります。

たとえば、

SNS投稿用のURLを短くしたい
QRコード用のURLを管理したい
システムから短縮URLを自動発行したい
キャンペーンごとにリンクを管理したい

といったケースです。

この記事では、nly.kr のURL短縮APIを使って、curl と JavaScript から短縮URLを作成する方法を紹介します。

今回使用するAPIのドキュメントはこちらです。

APIの基本仕様

エンドポイントは以下です。

POST https://nly.kr/api/shorten

Content-Type は以下を使用します。

application/x-www-form-urlencoded

認証にはAPIキーが必要です。

推奨されているヘッダーは X-API-Key です。

X-API-Key: your_API_KEY

Authorization: Bearer 形式も利用できます。

Authorization: Bearer your_API_KEY

レスポンスをJSONで受け取るため、以下も指定します。

Accept: application/json

パラメータ

短縮URLの作成には、以下の2つのパラメータを送信します。

パラメータ	型	必須	内容
`url`	String	Yes	短縮したい元URL（http / https）
`category`	String	Yes	URLのカテゴリキー

category も必須です。

たとえば ai や dev など、APIドキュメントに記載されているカテゴリキーを指定します。

この記事では例として ai を使用します。

curlで短縮URLを作成する

最も簡単な例です。

curl -X POST "https://nly.kr/api/shorten" \
  -H "X-API-Key: your_API_KEY" \
  -H "Accept: application/json" \
  -d "url=https://example.com" \
  -d "category=ai"

your_API_KEY の部分を自分のAPIキーに変更します。

元URLとして送信しているのは、

https://example.com

です。

正常に処理されると、JSON形式で短縮URLが返されます。

レスポンス例

成功時のレスポンスは次のような形式です。

{
  "status": "success",
  "short_url": "https://nly.kr/Ab3XkQ",
  "original_url": "https://example.com",
  "code": "Ab3XkQ",
  "member_idx": 123,
  "category": "ai"
}

実際に利用するときは、通常 short_url を取得すれば十分です。

たとえばJavaScriptなら、

console.log(data.short_url);

のように利用できます。

JavaScript（fetch）から呼び出す

JavaScriptでは fetch() を使って呼び出せます。

const apiKey = "your_API_KEY";
const longUrl = "https://example.com";
const category = "ai";

fetch("https://nly.kr/api/shorten", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "X-API-Key": apiKey,
    "Accept": "application/json",
  },
  body: new URLSearchParams({
    url: longUrl,
    category: category,
  }),
})
  .then(async (response) => {
    const data = await response.json().catch(() => null);

    if (!response.ok) {
      throw {
        status: response.status,
        data: data,
      };
    }

    return data;
  })
  .then((data) => {
    console.log("Short URL:", data.short_url);
  })
  .catch((error) => {
    console.error(
      "ERROR",
      error.status || "",
      error.data || error
    );
  });

成功すると、たとえば次のような短縮URLを取得できます。

https://nly.kr/Ab3XkQ

これをデータベースに保存したり、SNS投稿やメール、QRコード生成などに利用できます。

Bearer認証を使う場合

X-API-Key の代わりに Authorization ヘッダーを使用することもできます。

curl -X POST "https://nly.kr/api/shorten" \
  -H "Authorization: Bearer your_API_KEY" \
  -H "Accept: application/json" \
  -d "url=https://example.com" \
  -d "category=ai"

通常はドキュメントで推奨されている X-API-Key を使えばよいと思います。

エラー時のレスポンス

パラメータが不足している場合などは、エラーがJSON形式で返されます。

例：

{
  "status": "error",
  "message": "Category is required."
}

APIドキュメントでは、以下のHTTPステータスが案内されています。

HTTP Status	内容
`400`	Bad Request
`401`	Unauthorized
`405`	Method Not Allowed
`500`	Server Error

実装時は、HTTPステータスとレスポンス本文の両方を確認しておくと扱いやすくなります。

APIキーの扱いについて

一般的なAPI利用時の注意点として、APIキーを公開リポジトリや公開ページに直接書かないようにします。

特にブラウザで動くJavaScriptにAPIキーを直接埋め込むと、利用者からキーを確認できる状態になります。

そのため、本番環境では必要に応じてサーバー側からAPIを呼び出す構成を検討してください。

この記事のJavaScriptコードでは、APIの呼び出し方を分かりやすくするため、

const apiKey = "your_API_KEY";

としています。

まとめ

nly.kr のURL短縮APIでは、

POST https://nly.kr/api/shorten

に対して、

APIキー
元URL
カテゴリ

を送信することで、短縮URLをJSON形式で取得できます。

curlだけでなく、JavaScriptやPython、PHPなどからも利用できるため、短縮URLの自動生成をアプリケーションに組み込みたい場合に使えます。

APIドキュメント：

Web上で直接URLを短縮したい場合はこちら：

※この記事では、筆者が運営している nly.kr のAPIを使用しています。