/ 
Nexus-REST-0.002
River stage zero No dependents
/ Nexus::REST

NAME

Nexus::REST - Thin wrapper around Nexus's REST API

VERSION

version 0.002

SYNOPSIS

use Nexus::REST;

my $nexus = Nexus::REST->new('https://nexus.example.net', 'myuser', 'mypass');

DESCRIPTION

Nexus is an artifact repository manager from Sonatype.

This module is a thin wrapper around Sonatype' Nexus 3 REST API. It makes it easy to invoke the REST API endpoints without having to deal with data convertion into JSON and with HTTP.

The best way to get to know the API is using it's swagger UI. As of Nexus 3.6.1, this interface is available under the API item via the System sub menu of the Administration menu. For Nexus 3.3.0 through 3.6.0, use the following URL: "<nexus_url>/swagger-ui/".

CONSTRUCTOR

new URL, USERNAME, PASSWORD [, REST_CLIENT_CONFIG]

The constructor needs up to four arguments:

  • URL

    A string or a URI object denoting the base URL of the Nexus API service.

    This should contain the path prefix, which you can check at the bottom of the swagger UI page. It should be something like this:

    https://nexus.company.com/service

    It the path prefix isn't specified the prefix /service will be tried by default. (Note that up to Nexus 3.7 the default prefix was /service/siesta. Make sure to specify it if you're using an old version.)

    This is a required argument.

  • USERNAME

    The username of a Nexus user.

    It can be undefined if PASSWORD is also undefined. In such a case the user credentials are looked up in the .netrc file.

  • PASSWORD

    The HTTP password of the user. (This is the password the user uses to log in to Nexus's web interface.)

    It can be undefined, in which case the user credentials are looked up in the .netrc file.

  • REST_CLIENT_CONFIG

    A Nexus::REST object uses a REST::Client object to make the REST invocations. This optional argument must be a hash-ref that can be fed to the REST::Client constructor. Note that the URL argument overwrites any value associated with the host key in this hash.

REST METHODS

Nexus's REST API documentation lists a few "resources" which can be operated via the standard HTTP requests: GET, DELETE, PUT, and POST. Nexus::REST objects implement four methods called GET, DELETE, PUT, and POST to make it easier to invoke and get results from Nexus's REST endpoints.

All four methods need two arguments:

  • RESOURCE

    This is the resource's 'path'. For example, /rest/beta/assets and /rest/beta/search.

    This argument is required.

  • QUERY

    Some resource methods require or admit parameters which are passed as a query-string appended to the resource's path. You may construct the query string and append it to the RESOURCE argument yourself, but it's easier and safer to pass the arguments in a hash. This way the query string is constructed for you and its values are properly percent-encoded to avoid errors.

    This argument is optional for GET and DELETE. For PUT and POST it must be passed explicitly as undef if not needed.

The PUT and POST methods accept two more arguments:

  • VALUE

    This is the "entity" being PUT or POSTed. It can be any value, but usually is a hash-ref. The value is encoded as a JSON string using the JSON::encode method and sent with a Content-Type of application/json.

    It's usually easy to infer from the Nexus REST API documentation which kind of value you should pass to each resource.

    This argument is required.

  • HEADERS

    This optional argument allows you to specify extra HTTP headers that should be sent with the request. Each header is specified as a key/value pair in a hash.

All four methods return the value returned by the associated resource's method, as specified in the documentation, decoded according to its content type as follows:

  • application/json

    The majority of the API's resources return JSON values. Those are decoded using the decode method of a JSON object. Most of the endpoints return hashes, which are returned as a Perl hash-ref.

  • text/plain

    Those values are returned as simple strings.

Some endpoints don't return anything. In those cases, the methods return undef. The methods croak if they get any other type of values in return.

In case of errors (i.e., if the underlying HTTP method return an error code different from 2xx) the methods croak with a multi-line string like this:

ERROR: <CODE> - <MESSAGE>
<CONTENT-TYPE>
<CONTENT>

So, in order to treat errors you must invoke the methods in an eval block or use any of the exception handling Perl modules, such as Try::Tiny and Try::Catch.

GET RESOURCE [, QUERY]

Returns the RESOURCE as a Perl data structure.

DELETE RESOURCE [, QUERY]

Deletes the RESOURCE.

PUT RESOURCE, QUERY, VALUE [, HEADERS]

Creates RESOURCE based on VALUE.

POST RESOURCE, QUERY, VALUE [, HEADERS]

Updates RESOURCE based on VALUE.

UTILITY METHODS

get_iterator RESOURCE [, QUERY]

Some REST methods may return paginated results, such as: /rest/beta/assets, /rest/beta/components, /rest/beta/search, and /rest/beta/tasks. The pagination is controlled by means of a continuationToken field which can be returned by these methods. If it is, then you can get subsequent results by replaying the method and passing the continuationToken as a new parameter. You should do something like this:

%query = (repository => 'releases', version => '1.2.3');

do {
    my $search = $nexus->GET('/rest/beta/search', \%query);

    if ($search->{continuationToken}) {
        $query{continuationToken} = $search->{continuationToken};
    } else {
        delete $query{continuationToken};
    }

    foreach my $item (@{$search->{items}}) {
        # do something with $item
    }
} while (exists $query{continuationToken});

In order to make it easier to work with methods with paginated results, you can wrap them with this utility method. Like this:

my $iterator = $nexus->get_iterator('/rest/beta/search', {
    repository => 'releases',
    version    => '1.2.3',
});

while (my $item = $iterator->next) {
    # do something with $item
}

The get_iterator method returns an Nexus::REST::Iterator object, which provides a single method: next. Each call to next returns a new item until all are exausted, when it returns undef.

SEE ALSO

  • REST::Client

    Nexus::REST uses a REST::Client object to perform the low-level interactions.

REPOSITORY

https://github.com/gnustavo/Nexus-REST

AUTHOR

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by CPqD <www.cpqd.com.br>.

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