NAME Net::API::CPAN - Meta CPAN API SYNOPSIS use Net::API::CPAN; my $cpan = Net::API::CPAN->new( api_version => 1, ua => HTTP::Promise->new( %options ), debug => 4, ) || die( Net::API::CPAN->error, "\n" ); $cpan->api_uri( 'https://api.example.org' ); my $uri = $cpan->api_uri; $cpan->api_version(1); my $version = $cpan->api_version; VERSION v0.1.0 DESCRIPTION "Net::API::CPAN" is a client to issue queries to the MetaCPAN REST API. Make sure to check out the "TERMINOLOGY" section for the exact meaning of key words used in this documentation. CONSTRUCTOR new This instantiates a new Net::API::CPAN object. This accepts the following options, which can later also be set using their associated method. * "api_version" Integer. This is the "CPAN" API version, and defaults to 1. * "debug" Integer. This sets the debugging level. Defaults to 0. The higher and the more verbose will be the debugging output on STDERR. * "ua" An optional HTTP::Promise object. If not provided, one will be instantiated automatically. METHODS api_uri Sets or gets the "CPAN" API "URI" to use. This defaults to the "Net::API::CPAN" constant "API_URI" followed by the API version, such as: https://fastapi.metacpan.org/v1 This returns an URI object. api_version Sets or gets the "CPAN" API version. As of 2023-09-01, this can only 1 This returns a scalar object cache_file Sets or gets a cache file path to use instead of issuing the "HTTP" request. This affects how "fetch" works since it does not issue an actual "HTTP" request, but does not change the rest of the workflow. Returns a file object or "undef" if nothing was set. fetch This takes an object type, such as "author", "release", "file", etc, and the following options and performs an "HttP" request to the remote MetaCPAN REST API and return the appropriate data or object. If an error occurs, this set an error object and return "undef" in scalar context, and an empty list in list context. * "class" One of "Net::API::CPAN" classes, such as Net::API::CPAN::Author * "endpoint" The endpoint to access, such as "/author" * "headers" An array reference of headers with their corresponding values. * "method" The "HTTP" method to use. This defaults to "GET". This is case insensitive. * "payload" The "POST" payload to send to the remote MetaCPAN API. It must be already encoded in "UTF-8". * "postprocess" A subroutine reference or an anonymous subroutine that will be call backed, taking the data received as the sole argument and returning the modified data. * "query" An hash reference of key-value pairs representing the query string elements. This will be passed to "query_form" in URI, so make sure to check what data structure is acceptable by URI * "request" An HTTP::Promise::Request object. http_request The latest HTTP::Promise::Request issued to the remote MetaCPAN API server. http_response The latest HTTP::Promise::Response received from the remote MetaCPAN API server. json Returns a new JSON object. new_filter This instantiates a new Net::API::CPAN::Filter, passing whatever arguments were received, and setting the debugging mode too. API METHODS activity # Get all the release activity for author OALDERS in the last 24 months my $activity_obj = $cpan->activity( author => 'OALDERS', # distribution => 'HTTP-Message', # module => 'HTTP::Message', interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); # Get all the release activity that depend on HTTP::Message in the last 24 months my $activity_obj = $cpan->activity( # author => 'OALDERS', # distribution => 'HTTP-Message', module => 'HTTP::Message', interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); This method is used to query the CPAN REST API for the release activity for all, or for a given "author", or a given "distribution", or a given "module" dependency. An optional aggregation interval can be stipulated with "res" and it defaults to "1w" (set by the API). * "author" -> "/activity" If a string is provided representing a specific "author", this will issue a query to the API endpoint "/activity" to retrieve the release activity for that "author" for the past 24 months for the specified author, such as: /activity?author=OALDERS For example: my $activity_obj = $cpan->activity( author => 'OALDERS', interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); This would return, upon success, a Net::API::CPAN::Activity object containing release activity for the "author" "OALDERS" for the past 24 months. Note that the value of the "author" is case insensitive and will automatically be transformed in upper case, so you could also do: Possible options are: * "interval" Specifies an interval for the aggregate value. Defaults to "1w", which is 1 week. See ElasticSearch document for the proper value to use as interval. * "new" Limit the result to newly issued distributions. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "distribution" -> "/activity" If a string is provided representing a specific "distribution", this will issue a query to the API endpoint "/activity" to retrieve the release activity for that "distribution" for the past 24 months for the specified "distribution", such as: /activity?distribution=HTTP-Message For example: my $activity_obj = $cpan->activity( distribution => 'HTTP-Message', interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); This would return, upon success, a Net::API::CPAN::Activity object containing release activity for the "distribution" "HTTP-Message" for the past 24 months. Possible options are: * "interval" Specifies an interval for the aggregate value. Defaults to "1w", which is 1 week. See ElasticSearch document for the proper value to use as interval. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "module" -> "/activity" If a string is provided representing a specific "module", this will issue a query to the API endpoint "/activity" to retrieve the release activity that have a dependency on that "module" for the past 24 months, such as: /activity?res=1M&module=HTTP::Message For example: my $activity_obj = $cpan->activity( module => 'HTTP::Message', interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); This would return, upon success, a Net::API::CPAN::Activity object containing release activity for all the distributions depending on the "module" "HTTP::Message" for the past 24 months. Possible options are: * "interval" Specifies an interval for the aggregate value. Defaults to "1w", which is 1 week. See ElasticSearch document for the proper value to use as interval. * "new" Limit the result to newly issued distributions. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "new" -> "/activity" If "new" is provided with any value (true or not does not matter), this will issue a query to the API endpoint "/activity" to retrieve the new release activity in the past 24 months, such as: /activity?res=1M&new_dists=n For example: my $activity_obj = $cpan->activity( new => 1, interval => '1M', ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); This would return, upon success, a Net::API::CPAN::Activity object containing all new distributions release activity for the past 24 months. Possible options are: * "interval" Specifies an interval for the aggregate value. Defaults to "1w", which is 1 week. See ElasticSearch document for the proper value to use as interval. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. author # Retrieves the information details for the specified author my $author_obj = $cpan->author( 'OALDERS' ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); # Retrieves author information details for the specified pause IDs my $list_obj = $cpan->author( [qw( OALDERS NEILB )] ) || die( "Error with code: ", $cpan->error->code, " and message: ", $cpan->error->message ); # Queries authors information details my $list_obj = $cpan->author( query => 'Olaf', from => 10, size => 20, ) || die( $cpan->error ); # Queries authors information details using ElasticSearch format my $list_obj = $cpan->author( $filter_object ) || die( $cpan->error ); # Queries authors information using a prefix my $list_obj = $cpan->author( prefix => 'O' ) || die( $cpan->error ); # Retrieves authors information using their specified IDs my $list_obj = $cpan->author( user => [qw( FepgBJBZQ8u92eG_TcyIGQ 6ZuVfdMpQzy75_Mazx2_nw )] ) || die( $cpan->error ); This method is used to query the CPAN REST API for a specific "author", a list of "authors", or search an "author" using a query. It takes a string, an array reference, an hash or alternatively an hash reference as possible parameters. * "author" -> "/author/{author}" If a string is provided representing a specific "author", this will issue a query to the API endpoint "/author/{author}" to retrieve the information details for the specified author, such as: /author/OALDERS For example: my $author_obj = $cpan->author( 'OALDERS' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::Author object. Note that the value of the "author" is case insensitive and will automatically be transformed in upper case, so you could also do: my $author_obj = $cpan->author( 'OAlders' ) || die( $cpan->error ); The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * ["author"] -> "/author/by_ids" And providing an array reference of "authors" will trigger a query to the API endpoint "/author/by_ids", such as: /author/by_ids?id=OALDERS&id=NEILB For example: my $list_obj = $cpan->author( [qw( OALDERS NEILB )] ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Author objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "query" -> "/author" If the property "query" is provided, this will trigger a simple search query to the endpoint "/author", such as: /author?q=Tokyo For example: my $list_obj = $cpan->author( query => 'Tokyo', from => 10, size => 10, ) || die( $cpan->error ); will find all "authors" related to Tokyo. This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Author objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "prefix" -> "/author/by_prefix/{prefix}" However, if the property "prefix" is provided, this will issue a query to the endpoint "/author/by_prefix/{prefix}", such as: /author/by_prefix/O which will find all "authors" whose Pause ID starts with the specified prefix; in this example, the letter "O" For example: my $list_obj = $cpan->author( prefix => 'O' ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Author objects. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "user" -> "/author/by_user" And if the property "user" is provided, this will issue a query to the endpoint "/author/by_user", such as: /author/by_user?user=FepgBJBZQ8u92eG_TcyIGQ&user=6ZuVfdMpQzy75_Mazx2_nw which will fetch the information for the authors whose user ID are "FepgBJBZQ8u92eG_TcyIGQ" and "6ZuVfdMpQzy75_Mazx2_nw" (here respectively corresponding to the "authors" "OALDERS" and "HAARG") For example: my $list_obj = $cpan->author( user => [qw( FepgBJBZQ8u92eG_TcyIGQ 6ZuVfdMpQzy75_Mazx2_nw )] ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Author objects. However, note that not all "CPAN" account have a user ID, surprisingly enough. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/author/_search" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/author/_search" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Author objects. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. autocomplete This takes a string and will issue a query to the endpoint "/search/autocomplete" to retrieve the result set based on the autocomplete search query specified, such as: /search/autocomplete?q=HTTP For example: my $list_obj = $cpan->autocomplete( 'HTTP' ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::File objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. changes # Retrieves the specified distribution Changes file content my $change_obj = $cpan->changes( distribution => 'HTTP-Message' ) || die( $cpan->error ); # Retrieves one or more distribution Changes file details using author and release information my $change_obj = $cpan->changes( author => 'OALDERS', release => 'HTTP-Message-6.36' ) || die( $cpan->error ); # Same: my $change_obj = $cpan->changes( release => 'OALDERS/HTTP-Message-6.36' ) || die( $cpan->error ); # With multiple author and releases my $list_obj = $cpan->changes( author => [qw( OALDERS NEILB )], release => [qw( HTTP-Message-6.36 Data-HexDump-0.04 )] ) || die( $cpan->error ); # Same: my $list_obj = $cpan->changes( release => [qw( OALDERS/HTTP-Message-6.36 NEILB/Data-HexDump-0.04 )] ) || die( $cpan->error ); This method is used to query the CPAN REST API for one or more particular "release"'s "Changes" (or "CHANGES" depending on the release) file content. * "distribution" -> "/changes/{distribution}" If the property "distribution" is provided, this will issue a query to the endpoint "/changes/{distribution}" to retrieve a distribution Changes file details, such as: /changes/HTTP-Message For example: my $change_obj = $cpan->changes( distribution => 'HTTP-Message' ) || die( $cpan->error ); which will retrieve the "Changes" file information for the latest "release" of the specified "distribution", and return a Net::API::CPAN::Changes object upon success. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "release" -> "/changes/" * "author" and "release" -> "/changes/{author}/{release}" If the properties "author" and "release" have been provided or that the value of the property "release" has the form "author"/"release", this will issue a query to the endpoint "/changes/{author}/{release}" to retrieve an author distribution Changes file details: /changes/OALDERS/HTTP-Message-6.36 For example: my $change_obj = $cpan->changes( author => 'OALDERS', release => 'HTTP-Message-6.36' ) || die( $cpan->error ); # or my $change_obj = $cpan->changes( release => 'OALDERS/HTTP-Message-6.36' ) || die( $cpan->error ); which will retrieve the "Changes" file information for the specified "release", and return, upon success, a Net::API::CPAN::Changes object. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * ["author"] and ["release"] -> "/author/by_releases" And, if both properties "author" and "release" have been provided and are both an array reference of equal size, this will issue a query to the endpoint "/author/by_releases" to retrieve one or more distribution Changes file details using the specified author and release information, such as: /changes/by_releases?release=OALDERS%2FHTTP-Message-6.37&release=NEILB%2FData-HexDump-0.04 For example: my $list_obj = $cpan->changes( author => [qw( OALDERS NEILB )], release => [qw( HTTP-Message-6.36 Data-HexDump-0.04 )] ) || die( $cpan->error ); Alternatively, you can provide the property "release" having, as value, an array reference of "author"/"release", such as: my $list_obj = $cpan->changes( release => [qw( OALDERS/HTTP-Message-6.36 NEILB/Data-HexDump-0.04 )] ) || die( $cpan->error ); which will retrieve the "Changes" file information for the specified "releases", and return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Changes objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. clientinfo This issue a query to the endpoint "https://clientinfo.metacpan.org" and retrieves the information of the various base URL. It returns an hash reference with the following structure: { future => { domain => "https://fastapi.metacpan.org/", url => "https://fastapi.metacpan.org/v1/", version => "v1", }, production => { domain => "https://fastapi.metacpan.org/", url => "https://fastapi.metacpan.org/v1/", version => "v1", }, testing => { domain => "https://fastapi.metacpan.org/", url => "https://fastapi.metacpan.org/v1/", version => "v1", }, } Each of the URL is an URL object. contributor # Retrieves a list of module contributed to by the specified PauseID my $list_obj = $cpan->contributor( author => 'OALDERS' ) || die( $cpan->error ); # Retrieves a list of module contributors details my $list_obj = $cpan->contributor( author => 'OALDERS' release => 'HTTP-Message-6.37' ) || die( $cpan->error ); This method is used to query the CPAN REST API for either the list of "releases" a CPAN account has contributed to, or to get the list of "contributors" for a specified "release". * "author" -> "/contributor/by_pauseid/{author}" If the property "author" is provided, this will issue a query to the endpoint "/contributor/by_pauseid/{author}" to retrieve a list of module contributed to by the specified PauseID, such as: /contributor/by_pauseid/OALDERS For example: my $list_obj = $cpan->contributor( author => 'OALDERS' ) || die( $cpan->error ); This will, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Contributor objects containing the details of the release to which the specified "author" has contributed. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "author" and "release" -> "/contributor/{author}/{release}" And if the properties "author" and "release" are provided, this will issue a query to the endpoint "/contributor/{author}/{release}" to retrieve a list of release contributors details, such as: /contributor/OALDERS/HTTP-Message-6.36 For example: my $list_obj = $cpan->contributor( author => 'OALDERS' release => 'HTTP-Message-6.37' ) || die( $cpan->error ); This will, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Contributor objects containing the specified "release" information and the "pauseid" of all the "authors" who have contributed to the specified "release". You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. cover This method is used to query the CPAN REST API to the endpoint "/v1/cover/{release}" to get the "cover" information including "distribution" name, "release" name, "version" and download "URL", such as: /cover/HTTP-Message-6.37 For example: my $cover_obj = $cpan->cover( release => 'HTTP-Message-6.37', ) || die( $cpan->error ); It returns, upon success, a Net::API::CPAN::Cover object. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. diff # Retrieves a diff of two files with output as JSON my $diff_obj = $cpan->diff( file1 => 'AcREzFgg3ExIrFTURa0QJfn8nto', file2 => 'Ies7Ysw0GjCxUU6Wj_WzI9s8ysU', # Default accept => 'application/json', ) || die( $cpan->error ); # Retrieves a diff of two files with output as plain text my $diff_text = $cpan->diff( file1 => 'AcREzFgg3ExIrFTURa0QJfn8nto', file2 => 'Ies7Ysw0GjCxUU6Wj_WzI9s8ysU', # Default accept => 'text/plain', ) || die( $cpan->error ); # Retrieves a diff of two releases with output as JSON my $diff_obj = $cpan->diff( author1 => 'OALDERS', # This is optional if it is the same author2 => 'OALDERS', release1 => 'HTTP-Message-6.35' release2 => 'HTTP-Message-6.36' # Default accept => 'application/json', ) || die( $cpan->error ); # Retrieves a diff of two releases with output as plain text my $diff_text = $cpan->diff( author1 => 'OALDERS', # This is optional if it is the same author2 => 'OALDERS', release1 => 'HTTP-Message-6.35' release2 => 'HTTP-Message-6.36' # Default accept => 'text/plain', ) || die( $cpan->error ); # Retrieves a diff of the latest release and its previous version with output as JSON my $diff_obj = $cpan->diff( distribution => 'HTTP-Message', # Default accept => 'application/json', ) || die( $cpan->error ); # Retrieves a diff of the latest release and its previous version with output as plain text my $diff_text = $cpan->diff( distribution => 'HTTP-Message', # Default accept => 'text/plain', ) || die( $cpan->error ); This method is used to query the CPAN REST API to get the "diff" output between 2 files, or 2 releases. * "file1" and "file2" -> "/diff/file/{file1}/{file2}" If the properties "file1" and "file2" are provided, this will issue a query to the endpoint "/diff/file/{file1}/{file2}", such as: /diff/file/AcREzFgg3ExIrFTURa0QJfn8nto/Ies7Ysw0GjCxUU6Wj_WzI9s8ysU The result returned will depend on the optional "accept" property, which is, by default "application/json", but can also be set to "text/plain". When set to "application/json", this will retrieve the result as "JSON" data and return a Net::API::CPAN::Diff object. If this is set to "text/plain", then this will return a raw "diff" output as a string encoded in Perl internal utf-8 encoding. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "author1", "author2", "release1", and "release2" -> "/diff/release/{author1}/{release1}/{author2}/{release2}" If the properties "author1", "author2", "release1", and "release2" are provided, this will issue a query to the endpoint "/diff/release/{author1}/{release1}/{author2}/{release2}", such as: /diff/release/OALDERS/HTTP-Message-6.35/OALDERS/HTTP-Message-6.36 For example: my $diff_obj = $cpan->diff( author1 => 'OALDERS', # This is optional if it is the same author2 => 'OALDERS', release1 => 'HTTP-Message-6.35' release2 => 'HTTP-Message-6.36' # Default accept => 'application/json', ) || die( $cpan->error ); Note that, if "author1" and "author2" are the same, "author2" is optional. It is important, however, that the "release" specified with "release1" belongs to "author1" and the "release" specified with "release2" belongs to "author2" You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "distribution" -> "/diff/release/{distribution}" You can also specify the property "distribution", and this will issue a query to the endpoint "/diff/release/{distribution}", such as: /diff/release/HTTP-Message For example: my $diff_obj = $cpan->diff( distribution => 'HTTP-Message', # Default accept => 'application/json', ) || die( $cpan->error ); If "accept" is set to "application/json", which is the default value, this will return a Net::API::CPAN::Diff object representing the difference between the previous version and current version for the "release" of the "distribution" specified. If, however, "accept" is set to "text/plain", a string of the diff output will be returned encoded in Perl internal utf-8 encoding. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. distribution # Retrieves a distribution information details my $dist_obj = $cpan->distribution( 'HTTP-Message' ) || die( $cpan->error ); # Queries distribution information details using simple search my $list_obj = $cpan->distribution( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries distribution information details using advanced search with ElasticSearch my $list_obj = $cpan->distribution( $filter_object ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "distribution" information. * "distribution" -> "/distribution/{distribution}" If a string representing a "distribution" is provided, it will issue a query to the endpoint "/distribution/{distribution}" to retrieve a distribution information details, such as: /distribution/HTTP-Message For example: my $dist_obj = $cpan->distribution( 'HTTP-Message' ) || die( $cpan->error ); This will return, upon success, a Net::API::CPAN::Distribution object. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "query" -> "/distribution" If the property "query" is provided, this will trigger a simple search query to the endpoint "/distribution", such as: /distribution?q=HTTP For example: my $list_obj = $cpan->distribution( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Distribution objects. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/distribution" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/distribution" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Distribution objects. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. download_url # Retrieve the latest release download URL information details my $dl_obj = $cpan->download_url( 'HTTP::Message' ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve the specified "module" latest "release" "download_url" information. * "module" -> "/download_url/{module}" If a string representing a "module" is provided, it will issue a query to the endpoint "/download_url/{module}" to retrieve the download URL information details of the specified module, such as: /download_url/HTTP::Message This will return, upon success, a Net::API::CPAN::DownloadUrl object. The following options are also supported: * "dev" # Retrieves a development release my $dl_obj = $cpan->download_url( 'HTTP::Message', { dev => 1, version => '>1.01', }) || die( $cpan->error ); Specifies if the "release" is a development version. * "version" # Retrieve the download URL of a specific release version my $dl_obj = $cpan->download_url( 'HTTP::Message', { version => '1.01', }) || die( $cpan->error ); # or, using a range my $dl_obj = $cpan->download_url( 'HTTP::Message', { version => '<=1.01', }) || die( $cpan->error ); my $dl_obj = $cpan->download_url( 'HTTP::Message', { version => '>1.01,<=2.00', }) || die( $cpan->error ); Specifies the version requirement or version range requirement. Supported range operators are "==" "!=" "<=" ">=" "<" ">" "!" Separate the ranges with a comma when specifying multiple ranges. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. favorite # Queries favorites using a simple search my $list_obj = $cpan->favorite( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries favorites using a advanced search with ElasticSearch format my $list_obj = $cpan->favorite( $filter_object ) || die( $cpan->error ); # Retrieves favorites agregate by distributions as an hash reference # e.g.: HTTP-Message => 63 my $hash_ref = $cpan->favorite( aggregate => 'HTTP-Message' ) || die( $cpan->error ); # Same my $hash_ref = $cpan->favorite( agg => 'HTTP-Message' ) || die( $cpan->error ); # Same with multiple distributions my $hash_ref = $cpan->favorite( aggregate => [qw( HTTP-Message Data-HexDump)] ) || die( $cpan->error ); # Same my $hash_ref = $cpan->favorite( agg => [qw( HTTP-Message Data-HexDump)] ) || die( $cpan->error ); # Retrieves list of users who favorited a distribution as an array reference # e.g. [ '9nGbVdZ4QhO4Ia5ZhNpjtg', 'c4QLX0YORN6-quL15MGwqg', ... ] my $array_ref = $cpan->favorite( distribution => 'HTTP-Message' ) || die( $cpan->error ); # Retrieves user favorites information details my $list_obj = $cpan->favorite( user => 'q_15sjOkRminDY93g9DuZQ' ) || die( $cpan->error ); # Retrieves top favorite distributions a.k.a. leaderboard as an array reference my $array_ref = $cpan->favorite( leaderboard => 1 ) || die( $cpan->error ); # Retrieves list of recent favorite distribution my $list_obj = $cpan->favorite( recent => 1 ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "favorite" information. * "query" -> "/favorite" If the property "query" is provided, this will trigger a simple search query to the endpoint "/favorite", such as: /favorite?q=HTTP For example: my $list_obj = $cpan->favorite( query => 'HTTP' ) || die( $cpan->error ); which will find all "favorite" related to the query term "HTTP". This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/favorite" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/favorite" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. * "aggregate" or "agg" -> "/favorite/agg_by_distributions" If the property "aggregate" or "agg", for short, is provided, this will issue a query to the endpoint "/favorite/agg_by_distributions" to retrieve favorites agregate by distributions, such as: /favorite/agg_by_distributions?distribution=HTTP-Message&distribution=Data-HexDump For example: my $hash_ref = $cpan->favorite( aggregate => 'HTTP-Message' ) || die( $cpan->error ); my $hash_ref = $cpan->favorite( aggregate => [qw( HTTP-Message Data-HexDump)] ) || die( $cpan->error ); The "aggregate" value can be either a string representing a "distribution", or an array reference of "distributions" This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "distribution" -> "/favorite/users_by_distribution/{distribution}" If the property "distribution" is provided, will issue a query to the endpoint "/favorite/users_by_distribution/{distribution}" to retrieves the list of users who favorited the specified distribution, such as: /favorite/users_by_distribution/HTTP-Message For example: my $array_ref = $cpan->favorite( distribution => 'HTTP-Message' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "user" -> "/favorite/by_user/{user}" If the property "user" is provided, this will issue a query to the endpoint "/favorite/by_user/{user}" to retrieve the specified user favorites information details, such as: /favorite/by_user/q_15sjOkRminDY93g9DuZQ For example: my $list_obj = $cpan->favorite( user => 'q_15sjOkRminDY93g9DuZQ' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "leaderboard" -> "/favorite/leaderboard" If the property "leaderboard" is provided with any value true or false does not matter, this will issue a query to the endpoint "/favorite/leaderboard" to retrieve the top favorite distributions a.k.a. leaderboard, such as: /favorite/leaderboard For example: my $array_ref = $cpan->favorite( leaderboard => 1 ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "recent" -> "/favorite/recent" Finally, if the property "recent" is provided with any value true or false does not matter, this will issue a query to the endpoint "/favorite/recent" to retrieve the list of recent favorite distributions, such as: /favorite/recent For example: my $list_obj = $cpan->favorite( recent => 1 ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Favorite objects. The following options are also supported: * "page" An integer representing the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. file # Queries files using simple search my $list_obj = $cpan->file( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries files with advanced search using ElasticSearch my $list_obj = $cpan->file( $filter_object ) || die( $cpan->error ); # Retrieves a directory content my $list_obj = $cpan->file( author => 'OALDERS', release => 'HTTP-Message-6.36', dir => 'lib/HTTP', ) || die( $cpan->error ); # Retrieves a file information details my $file_obj = $cpan->file( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "file" information. * "query" -> "/file" If the property "query" is provided, this will trigger a simple search query to the endpoint "/file", such as: /file?q=HTTP For example: my $list_obj = $cpan->file( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); will find all "files" related to "HTTP". This would return a Net::API::CPAN::List object upon success. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/file" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/file" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. my $list_obj = $cpan->file( $filter_object ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::File objects. * "author", "release" and "dir" -> "/file/dir/{author}/{release}/{dir}" If the properties, "author", "release" and "dir" are provided, this will issue a query to the endpoint "/file/dir/{author}/{release}/{dir}" to retrieve the specified directory content, such as: /file/dir/OALDERS/HTTP-Message-6.36/lib/HTTP For example: my $list_obj = $cpan->file( author => 'OALDERS', release => 'HTTP-Message-6.36', dir => 'lib/HTTP', ) || die( $cpan->error ); For this to yield correct results, the "dir" specified must be a directory. This would return, upon success, a Net::API::CPAN::List object of all the files and directories contained within the specified directory. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "author", "release" and "path" -> "/file/{author}/{release}/{path}" If the properties, "author", "release" and "path" are provided, this will issue a query to the endpoint "/file/{author}/{release}/{path}" to retrieve the specified file (or directory) information details, such as: /file/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm For example: my $file_obj = $cpan->file( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::File object of the information retrieved. Note that the path can point to either a file or a directory within the given release. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. first This takes a string and will issue a query to the endpoint "/search/first" to retrieve the first result found based on the search query specified, such as: /search/first?q=HTTP For example: my $list_obj = $cpan->first( 'HTTP' ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::Module object. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. history # Retrieves the history of a given module my $list_obj = $cpan->history( type => 'module', module => 'HTTP::Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); # Retrieves the history of a given distribution file my $list_obj = $cpan->history( type => 'file', distribution => 'HTTP-Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); # Retrieves the history of a given module documentation my $list_obj = $cpan->history( type => 'documentation', module => 'HTTP::Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "file" history information. * "module" -> "/search/history/module" If the property "module" is provided, this will trigger a query to the endpoint "/search/history/module" to retrieve the history of a given module, such as: /search/history/module/HTTP::Message/lib/HTTP/Message.pm For example: my $list_obj = $cpan->history( type => 'module', module => 'HTTP::Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); will find all "module" history related to the module "HTTP::Message". This would return a Net::API::CPAN::List object upon success. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "file" -> "/search/history/file" If the property "file" is provided, this will trigger a query to the endpoint "/search/history/file" to retrieve the history of a given distribution file, such as: /search/history/file/HTTP-Message/lib/HTTP/Message.pm For example: my $list_obj = $cpan->history( type => 'file', distribution => 'HTTP-Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); will find all "files" history related to the distribution "HTTP-Message". This would return a Net::API::CPAN::List object upon success. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "documentation" -> "/search/history/documentation" If the property "documentation" is provided, this will trigger a query to the endpoint "/search/history/documentation" to retrieve the history of a given module documentation, such as: /search/history/documentation/HTTP::Message/lib/HTTP/Message.pm For example: my $list_obj = $cpan->history( type => 'documentation', module => 'HTTP::Message', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); will find all "documentation" history related to the module "HTTP::Message". This would return a Net::API::CPAN::List object upon success. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. mirror my $list_obj = $cpan->mirror; This would return, upon success, a Net::API::CPAN::List object. Actually there is no mirroring anymore, because for some time now CPAN runs on a CDN (Content Distributed Network) which performs the same result, but transparently. See more on this here This endpoint also has search capability, but given there is now only one entry, it is completely useless. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. module # Queries modules with a simple search my $list_obj = $cpan->module( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries modules with an advanced search using ElasticSearch my $list_obj = $cpan->module( $filter_object ) || die( $cpan->error ); # Retrieves the specified module information details my $module_obj = $cpan->module( module => 'HTTP::Message', ) || die( $cpan->error ); # And if you want to join with other object types my $module_obj = $cpan->module( module => 'HTTP::Message', join => [qw( release author )], ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "module" information. * "query" -> "/module" If the property "query" is provided, this will trigger a simple search query to the endpoint "/module", such as: /module?q=HTTP For example: my $list_obj = $cpan->module( query => 'HTTP' ) || die( $cpan->error ); will find all "modules" related to "HTTP". This would return a Net::API::CPAN::List object upon success. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/module" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/module" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. This would return a Net::API::CPAN::List object upon success. * $module -> "/module/{module}" If a string representing a "module" is provided, this will be used to issue a query to the endpoint "/module/{module}" to retrieve the specified module information details, such as: /module/HTTP::Message For example: my $module_obj = $cpan->module( module => 'HTTP::Message', join => [qw( release author )], ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::Module object. The following options are also supported: * "join" You can join a.k.a. merge other objects data by setting "join" to that object type, such as "release" or "author". "join" value can be either a string or an array of object types. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. package # Queries packages with a simple search my $list_obj = $cpan->package( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries packages with an advanced search using ElasticSearch my $list_obj = $cpan->package( $filter_object ) || die( $cpan->error ); # Retrieves the list of a distribution packages my $list_obj = $cpan->package( distribution => 'HTTP-Message' ) || die( $cpan->error ); # Retrieves the latest release and package information for the specified module my $package_obj = $cpan->package( 'HTTP::Message' ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "package" information. * "query" -> "/package" If the property "query" is provided, this will trigger a simple search query to the endpoint "/package", such as: /package?q=HTTP For example: my $list_obj = $cpan->package( query => 'HTTP' ) || die( $cpan->error ); will find all "packages" related to "HTTP". This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Package The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/package" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/package" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. * "distribution" -> "/package/modules/{distribution}" If the property "distribution" is provided, this will issue a query to the endpoint "/package/modules/{distribution}" to retrieve the list of a distribution packages, such as: /package/modules/HTTP-Message For example: my $list_obj = $cpan->package( distribution => 'HTTP-Message' ) || die( $cpan->error ); This would return, upon success, an array object containing all the modules name provided within the specified "distribution". You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * $package -> "/package/{module}" If a string representing a package name is directly passed, this will issue a query to the endpoint "/package/{module}" to retrieve the latest release and package information for the specified module, such as: /package/HTTP::Message For example: my $package_obj = $cpan->package( 'HTTP::Message' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::Package object. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. permission # Queries permissions with a simple search my $list_obj = $cpan->permission( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries permissions with an advanced search using ElasticSearch my $list_obj = $cpan->permission( $filter_object ) || die( $cpan->error ); # Retrieves permission information details for the specified author my $list_obj = $cpan->permission( author => 'OALDERS', from => 40, size => 20, ) || die( $cpan->error ); # Retrieves permission information details for the specified module my $list_obj = $cpan->permission( module => 'HTTP::Message', ) || die( $cpan->error ); # Retrieves permission information details for the specified modules my $list_obj = $cpan->permission( module => [qw( HTTP::Message Data::HexDump )], ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "package" information. * "query" -> "/permission" If the property "query" is provided, this will trigger a simple search query to the endpoint "/permission", such as: /permission?q=HTTP For example: my $list_obj = $cpan->permission( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); will find all "permissions" related to "HTTP". This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Permission objects. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/permission" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/permission" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. * "author" -> "/permission/by_author/{author}" If the property "author" is provided, this will trigger a simple search query to the endpoint "/permission/by_author/{author}" to retrieve the permission information details for the specified author, such as: /permission/by_author/OALDERS?from=40&q=HTTP&size=20 For example: my $list_obj = $cpan->permission( author => 'OALDERS', from => 40, size => 20, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Permission objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "module" -> "/permission/{module}" If the property "module" is provided, and its value is a string, this will issue a query to the endpoint "/permission/{module}" to retrieve permission information details for the specified module, such as: /permission/HTTP::Message For example: my $list_obj = $cpan->permission( module => 'HTTP::Message', ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::Permission object. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * ["module"] -> "/permission/by_module" If the property "module" is provided, and its value is an array reference, this will issue a query to the endpoint "/permission/by_module" to retrieve permission information details for the specified modules, such as: /permission/by_module?module=HTTP%3A%3AMessage&module=Data%3A%3AHexDump For example: my $list_obj = $cpan->permission( module => [qw( HTTP::Message Data::HexDump )], ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Permission objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. pod # Returns the POD of the given module in the # specified release in markdown format my $string = $cpan->pod( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', accept => 'text/x-markdown', ) || die( $cpan->error ); # Returns the POD of the given module in # markdown format my $string = $cpan->pod( module => 'HTTP::Message', accept => 'text/x-markdown', ) || die( $cpan->error ); # Renders the specified POD code into HTML my $html = $cpan->pod( render => qq{=encoding utf-8\n\n=head1 Hello World\n\nSomething here\n\n=oops\n\n=cut\n} ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "pod" documentation from specified modules and to render pod into "HTML" data. * "author", "release" and "path" -> "/pod/{author}/{release}/{path}" If the properties "author", "release" and "path" are provided, this will issue a query to the endpoint "/pod/{author}/{release}/{path}" to retrieve the POD of the given module in the specified release, such as: /pod/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm For example: my $string = $cpan->pod( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', accept => 'text/x-markdown', ) || die( $cpan->error ); This would return a string of data in the specified format, which can be one of "text/html", "text/plain", "text/x-markdown" or "text/x-pod". By default this is "text/html". The preferred data type is specified with the property "accept" The following options are also supported: * "accept" This value instructs the MetaCPAN API to return the pod data in the desired format. Supported formats are: "text/html", "text/plain", "text/x-markdown", "text/x-pod" You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "module" -> "/v1/pod/{module}" If the property "module" is provided, this will issue a query to the endpoint "/v1/pod/{module}" to retrieve the POD of the specified module, such as: /pod/HTTP::Message For example: my $string = $cpan->pod( module => 'HTTP::Message', accept => 'text/x-markdown', ) || die( $cpan->error ); Just like the previous one, this would return a string of data in the specified format (in the above example markdown), which can be one of "text/html", "text/plain", "text/x-markdown" or "text/x-pod". By default this is "text/html". The preferred data type is specified with the property "accept". The following options are also supported: * "accept" This value instructs the MetaCPAN API to return the pod data in the desired format. Supported formats are: "text/html", "text/plain", "text/x-markdown", "text/x-pod" You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "render" -> "/pod_render" If the property "render" is provided with a string of "POD" data, this will issue a query to the endpoint "/pod_render", such as: /pod_render?pod=%3Dencoding+utf-8%0A%0A%3Dhead1+Hello+World%0A%0ASomething+here%0A%0A%3Doops%0A%0A%3Dcut%0A For example: my $html = $cpan->pod( render => qq{=encoding utf-8\n\n=head1 Hello World\n\nSomething here\n\n=oops\n\n=cut\n} ) || die( $cpan->error ); This would return a string of "HTML" formatted data. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. rating # Queries permissions with a simple search my $list_obj = $cpan->rating( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Queries permissions with an advanced search using ElasticSearch format my $list_obj = $cpan->rating( $filter_object ) || die( $cpan->error ); # Retrieves rating information details of the specified distribution my $list_obj = $cpan->rating( distribution => 'HTTP-Tiny', ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "rating" historical data for the specified search query or "distribution". It is worth mentioning that although this endpoint still works, CPAN Ratings has been decommissioned some time ago, and thus its usefulness is questionable. * "query" -> "/rating" If the property "query" is provided, this will trigger a simple search query to the endpoint "/rating", such as: /rating?q=HTTP For example: my $list_obj = $cpan->rating( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); will find all "ratings" related to "HTTP". This would return a Net::API::CPAN::List object upon success. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/rating" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/rating" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. * "distribution" -> "/rating/by_distributions" If a property "distribution" is provided, this will issue a query to the endpoint "/rating/by_distributions" to retrieve rating information details of the specified distribution, such as: /rating/by_distributions?distribution=HTTP-Tiny For example: my $list_obj = $cpan->rating( distribution => 'HTTP-Tiny', ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Rating objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. release # Perform a simple query my $list_obj = $cpan->release( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); # Perform an advanced query using ElasticSearch format my $list_obj = $cpan->release( $filter_object ) || die( $cpan->error ); # Retrieves a list of all releases for a given author my $list_obj = $cpan->release( all => 'OALDERS', page => 2, size => 100, ) || die( $cpan->error ); # Retrieves a shorter list of all releases for a given author my $list_obj = $cpan->release( author => 'OALDERS' ) || die( $cpan->error ); # Retrieve a release information details my $release_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', ) || die( $cpan->error ); # Retrieves the latest distribution release information details my $release_obj = $cpan->release( distribution => 'HTTP-Message', ) || die( $cpan->error ); # Retrieves the list of contributors for the specified distributions my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', contributors => 1, ) || die( $cpan->error ); # Retrieves the list of release key files by category my $hash_ref = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', files => 1, ) || die( $cpan->error ); # Retrieves the list of interesting files for the given release my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', # You can also use just 'interesting' interesting_files => 1, ) || die( $cpan->error ); # Get latest releases by the specified author my $list_obj = $cpan->release( author => 'OALDERS', latest => 1, ) || die( $cpan->error ); # Get the latest releases for the specified distribution my $release_obj = $cpan->release( distribution => 'HTTP-Message', latest => 1, ) || die( $cpan->error ); # Retrieves the list of modules in the specified release my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', modules => 1, ) || die( $cpan->error ); # Get the list of recent releases my $list_obj = $cpan->release( recent => 1, ) || die( $cpan->error ); # get all releases by versions for the specified distribution my $list_obj = $cpan->release( versions => 'HTTP-Message', ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve "release" information. * "query" -> "/release" If the property "query" is provided, this will trigger a simple search query to the endpoint "/release", such as: /release?q=HTTP For example: my $list_obj = $cpan->release( query => 'HTTP', from => 10, size => 10, ) || die( $cpan->error ); will find all "releases" related to "HTTP". This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "from" An integer representing the offset starting from 0 within the total data. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * search filter -> "/release" And if a search filter is passed, this will trigger a more advanced ElasticSearch query to the endpoint "/release" using the "HTTP" "POST" method. See the Net::API::CPAN::Filter module on more details on what granular queries you can execute. * "all" -> "/release/all_by_author/{author}" If the property "all" is provided, this will issue a query to the endpoint "/release/all_by_author/{author}" to get all releases by the specified author, such as: /release/all_by_author/OALDERS?page=2&page_size=100 For example: my $list_obj = $cpan->release( all => 'OALDERS', page => 2, size => 100, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "page" An integer representing the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "author" -> "/release/by_author/{author}" If the property "author" alone is provided, this will issue a query to the endpoint "/release/by_author/{author}" to get releases by author, such as: /release/by_author/OALDERS For example: my $list_obj = $cpan->release( author => 'OALDERS' ) || die( $cpan->error ); This would return a Net::API::CPAN::List object upon success. Note that this is similar to "all", but returns a subset of all the author's data. The following options are also supported: * "page" An integer representing the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "author" and "release" -> "/v1/release/{author}/{release}" If the property "author" and "release" are provided, this will issue a query to the endpoint "/v1/release/{author}/{release}" tp retrieve a distribution release information, such as: /release/OALDERS/HTTP-Message-6.36 For example: my $release_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', ) || die( $cpan->error ); This would return a Net::API::CPAN::Release object upon success. The following options are also supported: * "join" You can join a.k.a. merge other objects data by setting "join" to that object type, such as "module" or "author". "join" value can be either a string or an array of object types. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "distribution" -> "/release/{distribution}" If the property "distribution" alone is provided, this will issue a query to the endpoint "/release/{distribution}" to retrieve a release information details., such as: /release/HTTP-Message For example: my $release_obj = $cpan->release( distribution => 'HTTP-Message', ) || die( $cpan->error ); This would return a Net::API::CPAN::Release object upon success. The following options are also supported: * "join" You can join a.k.a. merge other objects data by setting "join" to that object type, such as "module" or "author". "join" value can be either a string or an array of object types. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "contributors", "author" and "release" -> "/release/contributors/{author}/{release}" If the property "contributors", "author" and "release" are provided, this will issue a query to the endpoint "/release/contributors/{author}/{release}" to retrieve the list of contributors for the specified release, such as: /release/contributors/OALDERS/HTTP-Message-6.36 For example: my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', contributors => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. :List> object upon success. The following options are also supported: * "join" You can join a.k.a. merge other objects data by setting "join" to that object type, such as "module" or "author". "join" value can be either a string or an array of object types. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "files", "author" and "release" -> "/release/files_by_category/{author}/{release}" If the property "files", "author" and "release" are provided, this will issue a query to the endpoint "/release/files_by_category/{author}/{release}" to retrieve the list of key files by category for the specified release, such as: /release/files_by_category/OALDERS/HTTP-Message-6.36 For example: my $hash_ref = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', files => 1, ) || die( $cpan->error ); This would return an hash object of the following category names, each having, as their value, an array of the specified "release" files. The categories are: * "changelog" This is typically the "Changes" or "CHANGES" file. * "contributing" This is typically the "CONTRIBUTING.md" file. * "dist" This is typically other files that are part of the "release", such as "cpanfile", "Makefile.PL", "dist.ini", "META.json", "META.yml", "MANIFEST". * "install" This is typically the "INSTALL" file. * "license" This is typically the "LICENSE" file. * "other" This is typically the "README.md" file. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "interesting_files", "author" and "release" -> "/release/interesting_files/{author}/{release}" If the property "interesting_files" (or also just "interesting"), "author" and "release" are provided, this will issue a query to the endpoint "/release/interesting_files/{author}/{release}" to retrieve the list of release interesting files for the specified release, such as: /release/interesting_files/OALDERS/HTTP-Message-6.36 For example: my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', interesting_files => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "latest", and "author" -> "/release/latest_by_author/{author}" If the property "latest", and "author" are provided, this will issue a query to the endpoint "/release/latest_by_author/{author}" to retrieve the latest releases by the specified author, such as: /release/latest_by_author/OALDERS For example: my $list_obj = $cpan->release( author => 'OALDERS', latest => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "latest", and "distribution" -> "/release/latest_by_distribution/{distribution}" If the property "latest", and "distribution" are provided, this will issue a query to the endpoint "/release/latest_by_distribution/{distribution}" to retrieve the latest releases of the specified distribution, such as: /release/latest_by_distribution/HTTP-Message For example: my $release_obj = $cpan->release( distribution => 'HTTP-Message', latest => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::Release object representing the latest "release" for the specified "distribution". You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "modules", "author", and "release" -> "/release/modules/{author}/{release}" If the property "modules", "author", and "release" are provided, this will issue a query to the endpoint "/release/modules/{author}/{release}" to retrieve the list of modules in the specified distribution, such as: /release/modules/OALDERS/HTTP-Message-6.36 For example: my $list_obj = $cpan->release( author => 'OALDERS', release => 'HTTP-Message-6.36', modules => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "join" You can join a.k.a. merge other objects data by setting "join" to that object type, such as "module" or "author". "join" value can be either a string or an array of object types. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "recent" -> "/release/recent" If the property "recent", alone is provided, this will issue a query to the endpoint "/release/recent" to retrieve the list of recent releases, such as: /release/recent For example: my $list_obj = $cpan->release( recent => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "page" An integer specifying the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "versions" -> "distribution" If the property "versions" is provided having a value representing a "distribution", this will issue a query to the endpoint "/release/versions/{distribution}" to retrieve all releases by versions for the specified distribution, such as: /release/versions/HTTP-Message For example: my $list_obj = $cpan->release( distribution => 'HTTP-Message', # or, alternatively: version => '6.35,6.36,6.34', versions => [qw( 6.35 6.36 6.34 )], # Set this to true to get a raw list of version -> download URL instead of a list object # plain => 1, ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of all the "distribution" versions released. The following options are also supported: * "versions" An array reference of versions to return, or a string specifying the version(s) to return as a comma-sepated value * "plain" A boolean value specifying whether the result should be returned in plain mode. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API and here for the result in plain text mode . Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. reverse # Returns a list of all the modules who depend on the specified distribution my $list_obj = $cpan->reverse( distribution => 'HTTP-Message' ) || die( $cpan->error ); # Returns a list of all the modules who depend on the specified module my $list_obj = $cpan->reverse( module => 'HTTP::Message' ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve reverse dependencies, i.e. releases on "CPAN" that depend on the specified "distribution" or "module". * "distribution" -> "/reverse_dependencies/dist/{distribution}" If the property "distribution" representing a distribution is provided, this will issue a query to the endpoint "/reverse_dependencies/dist/{distribution}" to retrieve a list of all the modules who depend on the specified distribution, such as: /reverse_dependencies/dist/HTTP-Message For example: my $list_obj = $cpan->reverse( distribution => 'HTTP-Message' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "page" An integer representing the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. * "sort" A string representing a field specifying how the result is sorted. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "module" -> "/reverse_dependencies/module/{module}" If the property "module" representing a module is provided, this will issue a query to the endpoint "/reverse_dependencies/module/{module}" to retrieve a list of all the modules who depend on the specified module, such as: /reverse_dependencies/module/HTTP::Message For example: my $list_obj = $cpan->reverse( module => 'HTTP::Message' ) || die( $cpan->error ); This would return, upon success, a Net::API::CPAN::List object of Net::API::CPAN::Release objects. The following options are also supported: * "page" An integer representing the page offset starting from 1. * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. * "sort" A string representing a field specifying how the result is sorted. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. reverse_dependencies This is an alias for "reverse" search Provided with an hash or hash reference of options and this performs a search query and returns a Net::API::CPAN::List object, or an Net::API::CPAN::Scroll depending on the type of search query requested. There are 3 types of search query: 1. Using HTTP GET method 2. Using HTTP POST method with Elastic Search query 3. Using HTTP POST method with Elastic Search query using scroll source # Retrieves the source code of the given module path within the specified release my $string = $cpan->source( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); # Retrieves the full source of the latest, authorized version of the specified module my $string = $cpan->source( module => 'HTTP::Message' ) || die( $cpan->error ); This method is used to query the CPAN REST API to retrieve the source code or data of the specified "release" element or "module". * "author", "release" and "path" -> "/source/{author}/{release}/{path}" If the properties "author", "release" and "path" are provided, this will issue a query to the endpoint "/source/{author}/{release}/{path}" to retrieve the source code of the given module path within the specified release, such as: /source/OALDERS/HTTP-Message-6.36/lib/HTTP/Message.pm For example: my $string = $cpan->source( author => 'OALDERS', release => 'HTTP-Message-6.36', path => 'lib/HTTP/Message.pm', ) || die( $cpan->error ); This will return a string representing the source data of the file located at the specified "path" and "release". You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. * "module" -> "/source/{module}" If the properties "module" is provided, this will issue a query to the endpoint "/source/{module}" to retrieve the full source of the latest, authorized version of the specified module, such as: /source/HTTP::Message For example: my $string = $cpan->source( module => 'HTTP::Message' ) || die( $cpan->error ); This will return a string representing the source data of the specified "module". You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. suggest This takes a string and will issue a query to the endpoint "/search/autocomplete/suggest" to retrieve the suggested result set based on the autocomplete search query, such as: /search/autocomplete/suggest?q=HTTP For example: my $list_obj = $cpan->suggest( query => 'HTTP' ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Release::Suggest objects. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. top_uploaders This will issue a query to the endpoint "/release/top_uploaders" to retrieve an hash object of the top uploading "authors" with the total as the key's value, such as: /release/top_uploaders For example: my $hash_ref = $cpan->top_uploaders || die( $cpan->error ); This would return, upon success, an hash object of "author" and their recent total number of "release" upload on "CPAN" For example: { OALDERS => 12, NEILB => 7, } The following options are also supported: * "range" A string specifying the result range. Valid values are "all", "weekly", "monthly" or "yearly". It defaults to "weekly" * "size" An integer representing the size of each page, i.e. how many results are returned per page. This usually defaults to 10. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. web This takes a string and will issue a query to the endpoint "/search/web" to retrieve the result set based on the search query specified similar to the one on the MetaCPAN website, such as: /search/web?q=HTTP For example: my $list_obj = $cpan->web( query => 'HTTP', from => 0, size => 10, ) || die( $cpan->error ); This would, upon success, return a Net::API::CPAN::List object of Net::API::CPAN::Module objects. Search terms can be: * can be unqualified string, such as "paging" * can be author, such as "author:OALDERS" * can be module, such as "module:HTTP::Message" * can be distribution, such as "dist:HTTP-Message" The following options are also supported: * "collapsed" Boolean. When used, this forces a collapsed even when searching for a particular distribution or module name. * "from" An integer that represents offset to use in the result set. * "size" An integer that represents the number of results per page. You can try it out on CPAN Explorer to see the data returned by the CPAN REST API. Upon failure, an error will be set and "undef" will be returned in scalar context, or an empty list in list context. TERMINOLOGY The MetaCPAN REST API has quite a few endpoints returning sets of data containing properties. Below are the meanings of some of those keywords: * "author" For example "JOHNDOE" This is a "CPAN" id, and "distribution" author. It is also referred as "cpanid" * "cpanid" For example "JOHNDOE" See "author" * "contributor" For example: "JOHNDOE" A "contributor" is a "CPAN" author who is contributing code to an "author"'s "distribution". * "distribution" For example: "HTTP-Message" This is a bundle of modules distributed over "CPAN" and available for download. A "distribution" goes through a series of "releases" over the course of its lifetime. * "favorite" "favorite" relates to the appreciation a "distribution" received by having registered and non-registered user marking it as one of their favorite distributions. * "file" A "file" is an element of a "distribution" * "module" For example "HTTP::Message" This has the same meaning as in Perl. See perlmod for more information on Perl modules. * "package" For example "HTTP::Message" This is similar to "module", but a "package" is a "class" and a "module" is a file. * "permission" A "permission" defines the role a user has over a "distribution" and is one of "owner" or "co_maintainer" * "release" For example: "HTTP-Message-6.36" A "release" is a "distribution" being released with a unique version number. * "reverse_dependencies" This relates to the "distributions" depending on any given "distribution" ERRORS This module does not die or croak, but instead set an error object using "error" in Module::Generic and returns "undef" in scalar context, or an empty list in list context. You can retrieve the latest error object set by calling error inherited from Module::Generic Errors issued by this distributions are all instances of class Net::API::CPAN::Exception METACPAN OPENAPI SPECIFICATIONS From the information I could gather, I have produced the specifications for Open API v3.0.0 for your reference. You can also find it here in "JSON" format. AUTHOR Jacques Deguest SEE ALSO Meta CPAN API documentation , Net::API::CPAN::Activity, Net::API::CPAN::Author, Net::API::CPAN::Changes, Net::API::CPAN::Changes::Release, Net::API::CPAN::Contributor, Net::API::CPAN::Cover, Net::API::CPAN::Diff, Net::API::CPAN::Distribution, Net::API::CPAN::DownloadUrl, Net::API::CPAN::Favorite, Net::API::CPAN::File, Net::API::CPAN::Module, Net::API::CPAN::Package, Net::API::CPAN::Permission, Net::API::CPAN::Rating, Net::API::CPAN::Release Net::API::CPAN::Filter, Net::API::CPAN::List, Net::API::CPAN::Scroll Net::API::CPAN::Mock COPYRIGHT & LICENSE Copyright(c) 2023 DEGUEST Pte. Ltd. All rights reserved This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.