summaryrefslogtreecommitdiffstats
path: root/extensions/EditComments/lib/WebService.pm
blob: 9213f040747f6bd0e8e2fe3befe721e74dcc2b32 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This Source Code Form is "Incompatible With Secondary Licenses", as
# defined by the Mozilla Public License, v. 2.0.

package Bugzilla::Extension::EditComments::WebService;

use strict;
use warnings;

use base qw(Bugzilla::WebService);

use Bugzilla::Error;
use Bugzilla::Util qw(trim);
use Bugzilla::WebService::Util qw(validate);

sub comments {
    my ($self, $params) = validate(@_, 'comment_ids');
    my $dbh  = Bugzilla->switch_to_shadow_db();
    my $user = Bugzilla->user;

    if (!defined $params->{comment_ids}) {
        ThrowCodeError('param_required',
                       { function => 'Bug.comments',
                         param    => 'comment_ids' });
    }

    my @ids = map { trim($_) } @{ $params->{comment_ids} || [] };
    my $comment_data = Bugzilla::Comment->new_from_list(\@ids);

    # See if we were passed any invalid comment ids.
    my %got_ids = map { $_->id => 1 } @$comment_data;
    foreach my $comment_id (@ids) {
        if (!$got_ids{$comment_id}) {
            ThrowUserError('comment_id_invalid', { id => $comment_id });
        }
    }

    # Now make sure that we can see all the associated bugs.
    my %got_bug_ids = map { $_->bug_id => 1 } @$comment_data;
    $user->visible_bugs([ keys %got_bug_ids ]); # preload cache for visibility check
    Bugzilla::Bug->check($_) foreach (keys %got_bug_ids);

    my %comments;
    foreach my $comment (@$comment_data) {
        if ($comment->is_private && !$user->is_insider) {
            ThrowUserError('comment_is_private', { id => $comment->id });
        }
        $comments{$comment->id} = $comment->body;
    }

    return { comments => \%comments };
}

sub rest_resources {
    return [
        qr{^/editcomments/comment/(\d+)$}, {
            GET => {
                method => 'comments',
                params => sub {
                    return { comment_ids => $_[0] };
                },
            },
        },
        qr{^/editcomments/comment$}, {
            GET => {
                method => 'comments',
            },
        },
    ];
};


1;

__END__

=head1 NAME

Bugzilla::Extension::EditComments::Webservice - The EditComments WebServices API

=head1 DESCRIPTION

This module contains API methods that are useful to user's of bugzilla.mozilla.org.

=head1 METHODS

=head2 comments

B<EXPERIMENTAL>

=over

=item B<Description>

This allows you to get the raw comment text about comments, given a list of comment ids.

=item B<REST>

To get all comment text for a list of comment ids:

GET /bug/editcomments/comment?comment_ids=1234&comment_ids=5678...

To get comment text for a specific comment based on the comment ID:

GET /bug/editcomments/comment/<comment_id>

The returned data format is the same as below.

=item B<Params>

=over

=item C<comment_ids> (required)

C<array> An array of integer comment_ids. These comments will be
returned individually, separate from any other comments in their
respective bugs.

=item B<Returns>

1 item is returned:

=over

=item C<comments>

Each individual comment requested in C<comment_ids> is returned here,
in a hash where the numeric comment id is the key, and the value
is the comment's raw text.

=back

=item B<Errors>

In addition to standard Bug.get type errors, this method can throw the
following additional errors:

=over

=item 110 (Comment Is Private)

You specified the id of a private comment in the C<comment_ids>
argument, and you are not in the "insider group" that can see
private comments.

=item 111 (Invalid Comment ID)

You specified an id in the C<comment_ids> argument that is invalid--either
you specified something that wasn't a number, or there is no comment with
that id.

=back

=item B<History>

=over

=item Added in BMO Bugzilla B<4.2>.

=back

=back

=back

See L<Bugzilla::WebService> for a description of how parameters are passed,
and what B<STABLE>, B<UNSTABLE>, and B<EXPERIMENTAL> mean.