| 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'
MC/DC100%1/1
shift() || 'E0000'
shift()
Truth table100%2/2
A
A= shift()
| |||||||||||||
| 234 | 4 | my @args = @_; | |||||||||||
| 235 | 4 | my $cache = $self->cache; | |||||||||||
| 236 | 4 | ▶ | if (my $tpl = $cache->get($name)) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 237 | 2 | ▶ | return trim($tpl) unless scalar @args; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 238 | 0 | return trim(sprintf($tpl, @args)); | |||||||||||
| 239 | } | ||||||||||||
| 240 | 2 | ▶ | my $tpl = data_section(__PACKAGE__, $name) // ''; | ||||||||||
|
Condition50%1/2
data_section(__PACKAGE__, $name) // ""
MC/DC0%0/1
data_section(__PACKAGE__, $name) // ""
data_section(__PACKAGE__, $name)
Truth table50%1/2
A
A= data_section(__PACKAGE__, $name)
| |||||||||||||
| 241 | 2 | $cache->set($name => $tpl); | |||||||||||
| 242 | 2 | ▶ | return trim($tpl) unless scalar @args; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 243 | 1 | return trim(sprintf($tpl, @args)); | |||||||||||
| 244 | } | ||||||||||||
| 245 | |||||||||||||
| 246 | 2 | 1; | |||||||||||
| 247 | |||||||||||||
| 248 | __DATA__ | ||||||||||||