JAMADAM.COM

「縮 REST API」は、URL短縮/転送サービス「縮.jp」の機能を、アプリケーションから利用するためのインターフェースを提供します。

全てのAPIは下記のURL以下で提供されます。

http://api.xn--jj0a.jp/

現在サポートされている操作は、短縮URLの生成(generate.jsonへのPOST)と短縮URLの展開(lookup.jsonへのGET)です。いずれもレスポンスとしてJSONを返します。また、クエリーとしてcallbackを渡すことでJSONPを受け取ることもできるかもしれません。

GENERATE 

任意のURLを渡すことで、新規に短縮URLを生成します。

パラメータ

• fUrl(必須)
  短縮対象のURL。http://かhttps://で始まる必要があります。
• customId(オプション)
  任意の漢字の組み合わせで短縮URLの識別子を指定します。utf8でパーセントエンコードしてください。
• offset(オプション)
  fUrlで指定したURLに対する既設の短縮URLがひとつ以上存在する場合、このパラメータに0以上の数値を指定することで任意の候補を選択することができます。既設URLは文字数の短い順に並んでいます。offsetが既設URLの数より大きいとき、新しいURLが生成されます。このパラメータは特殊な目的がない場合は指定しないでください。

リクエスト例

POST /generate.json

fUrl=http://example.com&id=%E4%B8%83

レスポンス例

{"result":{"fUrl":"http://example.com/","generated":"http://縮.jp/七"}}

LOOKUP

既存の短縮URLの識別子を受け取り、元のURLを返します。識別子はUTF-8でパーセントエンコードしてください。

パラメータ

• id(必須)
  URLの識別子を指定します。
• hash
  後方互換性のための、idの別名です。(廃止の予定)

リクエスト

GET /lookup.json?id=%E4%B8%83

レスポンス

{"result":{"fUrl":"http://example.com"}}

共通

HTTPレスポンスコード

正常/エラーに関わらず「200 OK」を返します。

エラー時のレスポンスボディ

下記の書式でJSONデータを返します。

{"error":"[エラーコード] [説明]"}

 エラーコード一覧

• 400: generateの際、fUrlの書式が正しくない、customIdに不正な文字が含まれる、など。
• 409: generateの際、customIdがすでに使用されている、など。
• 404: lookupの際、指定のidが存在しない、など。

実装例

generate.jsonを利用して短縮URLを取得するPerlコードは以下のようになります。

use LWP::UserAgent;
use JSON::XS;

my $generated = _shuku('http://example.com');

sub _shuku {
    my $ua = LWP::UserAgent->new;
    my $res = $ua->post('http://api.xn--jj0a.jp/generate.json', {'fUrl' => $_[0]});
    my $obj = decode_json $res->content();
    my $decoded = $obj->{result}->{generated};
    utf8::decode($decoded);
    
    return $decoded;
}