MetaCPAN::API(3)

💖 MetaCPAN::API — the manual, but make it a group chat 💖

okay bestie, so this is the page for MetaCPAN::API(3), part of the User Contributed Perl Documentation situation. And ngl, I have to tell you something right off the bat: this module is DEPRECATED. Like, "we don't talk about it" deprecated. But you're here, you're reading, so let's give it the full tour anyway, because it's honestly kinda iconic even in retirement. 🫶

---

✨ NAME ✨

MetaCPAN::API — a comprehensive, DWIM-featured API to MetaCPAN. Also: DEPRECATED. 💀

---

🌸 VERSION 🌸

version 0.51

---

🎀 SYNOPSIS 🎀

the simple usage, the little starter pack:

# simple usage
my $mcpan  = MetaCPAN::API->new();
my $author = $mcpan->author('XSAWYERX');
my $dist   = $mcpan->release( distribution => 'MetaCPAN-API' );

and then the advanced usage, with cache, which was contributed by Kent Fredric, shoutout to them 💜:

# advanced usage with cache (contributed by Kent Fredric)
require CHI;
require WWW::Mechanize::Cached;
require HTTP::Tiny::Mech;
require MetaCPAN::API;

my $mcpan = MetaCPAN::API->new(
  ua => HTTP::Tiny::Mech->new(
    mechua => WWW::Mechanize::Cached->new(
      cache => CHI->new(
        driver => 'File',
        root_dir => '/tmp/metacpan-cache',
      ),
    ),
  ),
);

---

🦋 DESCRIPTION 🦋

so back in the day, this was the original, hopefully-complete, API-compliant interface to MetaCPAN (<https://metacpan.org>). it was the moment. it was serving. and then... it got superseded by MetaCPAN::Client. the torch was passed, bestie. 🔥

---

💀 DEPRECATED 💀

THIS MODULE IS DEPRECATED, DO NOT USE!

not me being dramatic, that's literally what it says. like, all caps and everything. 😭

this module has been completely rewritten to address a multitude of problems, and it now lives under its new official name: MetaCPAN::Client.

please do not use this module. fr fr. 🙈

---

👑 ATTRIBUTES 👑

✨ base_url ✨

my $mcpan = MetaCPAN::API->new(
    base_url => 'http://localhost:9999',
);

this attribute is what you use for REST requests. you set it to wherever MetaCPAN is actually reachable. by default it's already set correctly, so no stress — but if you're running a local instance of MetaCPAN, or you use a local mirror, or you tunnel it through a local port, or literally any of those things, you're gonna want to change this.

Default: https://fastapi.metacpan.org/v1.

this attribute is read-only (immutable), meaning once it's set on initialize (via new()), you cannot change it. if you need to change it, create a new instance of MetaCPAN::API. and why is it immutable, you ask? because it's better. 💅

🌈 ua 🌈

this attribute holds the user agent used for running the REST request to the server. it is specifically set to HTTP::Tiny, so if you want to set it manually, make sure it's of HTTP::Tiny. no substitutions, bestie.

HTTP::Tiny is used as part of the philosophy of keeping it tiny. that's the whole vibe. ✨

this attribute is read-only (immutable), meaning once it's set on initialize (via new()), you cannot change it. if you need to, create a new instance of MetaCPAN::API. why is it immutable? because it's better. (yes, same line, it's a whole thing, it's giving catchphrase)

🍓 ua_args 🍓

my $mcpan = MetaCPAN::API->new(
    ua_args => [ agent => 'MyAgent' ],
);

the arguments that get handed to the HTTP::Tiny user agent.

this attribute is read-only (immutable), meaning once it's set on initialize (via new()), you cannot change it. if you need to, create a new instance of MetaCPAN::API. why is it immutable? because it's better. (again. consistent queen.)

the default is a user agent string: MetaCPAN::API/$version.

---

🧚 METHODS 🧚

⭐ fetch ⭐

my $result = $mcpan->fetch('/release/distribution/Moose');

# with parameters
my $more = $mcpan->fetch(
    '/release/distribution/Moose',
    param => 'value',
);

this is a helper method for API implementations. it fetches a path from MetaCPAN, decodes the JSON from the content variable, and returns it. that's the whole job. clean. simple. slay. 💅

you don't really need to use it, but you can, in case you want to write your own extension implementation to MetaCPAN::API. main character energy, honestly.

it accepts an additional hash as GET parameters.

🌸 post 🌸

# /release&content={"query":{"match_all":{}},"filter":{"prefix":{"archive":"Cache-Cache-1.06"}}}
my $result = $mcpan->post(
    'release',
    {
        query  => { match_all => {} },
        filter => { prefix => { archive => 'Cache-Cache-1.06' } },
    },
);

the POST equivalent of the fetch() method. it gets the path and the JSON request. that's it, that's the method. ✨

---

💜 AUTHOR 💜

Sawyer X <xsawyerx@cpan.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2011 by Sawyer X.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay and that's the whole page, bestie!! 🫶 this manual page is from perl v5.42.0, dated 2025-07-25, and the page itself is MetaCPAN::API(3). mwah, love that for us. go use MetaCPAN::Client though. seriously. 💖✨👑