API.pm

filter: Statementstmt 97.2% 35 / 36 Branchbran 83.3% 5 / 6 Conditioncond 75.0% 3 / 4 MC/DCmcdc 50.0% 1 / 2 Subroutinesub 100% 9 / 9 Podpod 100% 1 / 1 totaltotal 93.1% 54 / 58 CC 6 SCAR 11.6
CC
6
Cov
93%
hint
6.1
BEGIN
1.0
BEGIN
1.0
CRAP 3.2
« Plugin/API.pm ↑ Summary
1 package WWW::Suffit::API;
2 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 =encoding utf-8
7  
8 =head1 NAME
9  
10 WWW::Suffit::API - The Suffit API
11  
12 =head1 VERSION
13  
14 API Version 1.06
15  
16 =head1 DESCRIPTION
17  
18 This library provides server API methods and describe it
19  
20 =head2 MEDIA TYPES
21  
22 The API currently supports only JSON as an exchange format. Be sure to set both the C<Content-Type>
23 and C<Accept> headers for every request as C<application/json>.
24  
25 All Date objects are returned in L<ISO 8601|https://tools.ietf.org/html/rfc3339> format: C<YYYY-MM-DDTHH:mm:ss.SSSZ>
26 or in unixtime format (epoch), eg.: C<1682759233>
27  
28 =head2 CHARACTER SET
29  
30 API supports a subset of the UTF-8 specification. Specifically, any character that can be encoded in
31 three bytes or less is supported. BMP characters and supplementary characters that must be encoded
32 using four bytes aren't supported at this time.
33  
34 =head2 HTTP METHODS
35  
36 Where possible, the we strives to use appropriate HTTP methods for each action.
37  
38 =head3 GET
39  
40 Used for retrieving objects
41  
42 =head3 POST
43  
44 Used for creating objects or performing custom actions (such as user lifecycle operations).
45 For POST requests with no C<body> param, set the C<Content-Length> header to zero.
46  
47 =head3 PUT
48  
49 Used for replacing objects or collections. For PUT requests with no C<body> param, set the C<Content-Length> header to zero.
50  
51 =head3 PATCH
52  
53 Used for partially updating objects
54  
55 =head3 DELETE
56  
57 Used for deleting objects
58  
59 =head2 IP ADDRESS
60  
61 The public IP address of your application is automatically used as the client IP address for your request.
62 The API supports the standard C<X-Forwarded-For> HTTP header to forward the originating client's IP address
63 if your application is behind a proxy server or acting as a sign-in portal or gateway.
64  
65 B<Note:> The public IP address of your trusted web application must be a part of the allowlist in your
66 org's network security settings as a trusted proxy to forward the user agent's original IP address
67 with the C<X-Forwarded-For> HTTP header.
68  
69 =head2 ERRORS
70  
71 All successful requests return a 200 status if there is content to return or a 204 status
72 if there is no content to return.
73  
74 All requests that result in an error return the appropriate 4xx or 5xx error code with a custom JSON
75 error object:
76  
77 {
78 "code": "E0001",
79 "error": "API validation failed",
80 "status": false
81 }
82  
83 or
84  
85 {
86 "code": "E0001",
87 "message": "API validation failed",
88 "status": false
89 }
90  
91 =over 4
92  
93 =item code
94  
95 A code that is associated with this error type
96  
97 =item error
98  
99 A natural language explanation of the error
100  
101 =item message
102  
103 A natural language explanation of the error (=error)
104  
105 =item status
106  
107 Any errors always return the status false
108  
109 =back
110  
111 List of codes see L<WWW::Suffit::API/"ERROR CODES">
112  
113 =head2 AUTHENTICATION
114  
115 Suffit APIs support two authentication options: session and tokens.
116  
117 The Suffit API requires the custom HTTP authentication scheme Token or Bearer for API token authentication.
118 Requests must have a valid API token specified in the HTTP Authorization header with the Token/Bearer
119 scheme or HTTP X-Token header.
120  
121 For example:
122  
123 X-Token: 00QCjAl4MlV-WPXM...0HmjFx-vbGua
124 Authorization: Token 00QCjAl4MlV-WPXM...0HmjFx-vbGua
125 Authorization: Bearer 00QCjAl4MlV-WPXM...0HmjFx-vbGua
126  
127 =head1 METHODS
128  
129 This class inherits all methods from L<Mojo::Base> and implements the following new ones
130  
131 =head2 hint
132  
133 my $hint = $api->hint;
134 my $hint = $api->hint('E1234');
135  
136 Get hint by error code
137  
138 =head2 ERROR CODES
139  
140 List of common Suffit API error codes
141  
142 =over 4
143  
144 =item B<E0xxx> -- General API error codes
145  
146 B<E01xx>, B<E02xx>, B<E03xx>, B<E04xx> and B<E05xx> are reserved as HTTP errors
147  
148 API | HTTP | DESCRIPTION
149 -------+-------+-------------------------------------------------
150 E0000 [ * ] Ok (general)
151 E0100 [100] Continue
152 E0200 [200] OK (HTTP)
153 E0300 [300] Multiple Choices
154 E0400 [400] Bad Request
155 E0500 [500] Internal Server Error
156  
157 =item B<E10xx> -- Public API error codes
158  
159 B<E1000-E1029> - authentication and authorization Suffit API error codes.
160 See L<WWW::Suffit::Server::Auth/"ERROR CODES"> for details
161  
162 B<E1030-E1059> - public Suffit API error codes.
163 See L<WWW::Suffit::Server::API/"ERROR CODES"> for details
164  
165 =item B<E11xx> -- Private API error codes
166  
167 B<E1100-E1109> - V1 Suffit API error codes.
168 See L<WWW::Suffit::Server::API::V1/"ERROR CODES"> for details
169  
170 B<E1110-E1119> - NoAPI Suffit API error codes.
171 See L<WWW::Suffit::Server::API::NoAPI/"ERROR CODES"> for details
172  
173 B<E1120-E1199> - User profile Suffit API error codes.
174 See L<WWW::Suffit::Server::API::User/"ERROR CODES"> for details
175  
176 =item B<E12xx> -- Admin API error codes
177  
178 B<E1200-E1299> - Admin Suffit API error codes.
179 See L<WWW::Suffit::Server::API::Admin/"ERROR CODES"> for details
180  
181 =item B<E13xx> -- AuthDB error codes
182  
183 B<E1300-E1399> - AuthDB error codes.
184 See L<WWW::Suffit::AuthDB/"ERROR CODES"> for details
185  
186 =item B<E14xx> -- Error codes are reserved for future use
187  
188 =item B<E15xx> -- Error codes are reserved for future use
189  
190 =item B<E16xx> -- Error codes are reserved for future use
191  
192 =item B<E17xx> -- Error codes are reserved for future use
193  
194 =item B<E18xx> -- Error codes are reserved for future use
195  
196 =item B<E19xx> -- Error codes are reserved for future use
197  
198 =item B<E7xxx> -- Application error code
199  
200 Error codes for user applications
201  
202 =back
203  
204 =head1 AUTHOR
205  
206 Serż Minus (Sergey Lepenkov) L<https://www.serzik.com> E<lt>abalama@cpan.orgE<gt>
207  
208 =head1 COPYRIGHT
209  
210 Copyright (C) 1998-2026 D&D Corporation
211  
212 =head1 LICENSE
213  
214 This program is distributed under the terms of the Artistic License Version 2.0
215  
216 See the C<LICENSE> file or L<https://opensource.org/license/artistic-2-0> for details
217  
218 =cut
219  
220 2 our $VERSION = '1.06';
221  
222 2 ▶use Mojo::Base -base;
Subroutine BEGIN: called CC=1 SCAR=0.0
223  
224 2 ▶use Mojo::Loader qw/data_section/;
Subroutine BEGIN: called CC=1 SCAR=0.0
225 2 ▶use Mojo::Util qw/trim/;
Subroutine BEGIN: called CC=1 SCAR=0.0
226  
227 2 ▶use WWW::Suffit::Cache;
Subroutine BEGIN: called CC=1 SCAR=0.0
228  
229 1 ▶has cache => sub { WWW::Suffit::Cache->new };
Subroutine __ANON__: called CC=1 SCAR=0.0
230  
231 4 ▶sub hint {
Subroutine hint: called CC=6 SCAR=18.1
Pod documented
232 4 my $self = shift;
233 4 ▶ my $name = shift || 'E0000';
Condition100%2/2
shift() || 'E0000'
l!l
31
MC/DC100%1/1
shift() || 'E0000'
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
234 4 my @args = @_;
235 4 my $cache = $self->cache;
236 4 ▶ if (my $tpl = $cache->get($name)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $tpl = $cache->get($name)) 2 2 4
237 2 ▶ return trim($tpl) unless scalar @args;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar @args 2 0 2
238 0 return trim(sprintf($tpl, @args));
239 }
240 2 ▶ my $tpl = data_section(__PACKAGE__, $name) // '';
Condition50%1/2
data_section(__PACKAGE__, $name) // ""
l!l
20
MC/DC0%0/1
data_section(__PACKAGE__, $name) // ""
data_section(__PACKAGE__, $name)
Truth table50%1/2
A
A= data_section(__PACKAGE__, $name)
Aresult
11
00
241 2 $cache->set($name => $tpl);
242 2 ▶ return trim($tpl) unless scalar @args;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar @args 1 1 2
243 1 return trim(sprintf($tpl, @args));
244 }
245  
246 2 1;
247  
248 __DATA__
« Plugin/API.pm ↑ Summary