Also, in my experience writing tests for your module generally gives you a good indication about the quality of the API: if your tests look straight-forward, the API is probably good. update: or rather, if your tests look clumsy, the API is probably bad.

For your specific instance, I would probably write a test like so (method and class-names made up):

# using Test::More...

my $input_string = "some input data";
my $proc = Data::Processor->new( string => $input_string );

my @out_filenames = $proc->names;

is_deeply(\@out_filenames,[qw(some list of filenames)]);

is($proc->data($some_filename),"data for filename");

$proc->close();
[download]

my $proc = Data::Processor->( file => "some filename");
# or                          handle => \*DATA

for my $name ($proc->names) {
  $proc->write( $some_filename, file => $name      );
# or                            handle => \*STDOUT
}
[download]

I wouldn't return a hashref with all the filenames and data in it - chances are, that users who want to access the data directly aren't interested in all files, plus, if your archive is big, it would consume a lot of memory.