File Coverage

blib/lib/WWW/Suffit/API.pm

Criterion	Covered	Total	%
statement	31	32	96.8
branch	5	6	83.3
condition	3	4	75.0
subroutine	8	8	100.0
pod	1	1	100.0
total	48	51	94.1

package WWW::Suffit::API;
use warnings;
use strict;
use utf8;

=encoding utf-8

=head1 NAME

WWW::Suffit::API - The Suffit API

=head1 VERSION

API Version 1.06

=head1 DESCRIPTION

This library provides server API methods and describe it

=head2 MEDIA TYPES

The API currently supports only JSON as an exchange format. Be sure to set both the C
and C headers for every request as C.

All Date objects are returned in L format: C
or in unixtime format (epoch), eg.: C<1682759233>

=head2 CHARACTER SET

API supports a subset of the UTF-8 specification. Specifically, any character that can be encoded in
three bytes or less is supported. BMP characters and supplementary characters that must be encoded
using four bytes aren't supported at this time.

=head2 HTTP METHODS

Where possible, the we strives to use appropriate HTTP methods for each action.

=head3 GET

Used for retrieving objects

=head3 POST

Used for creating objects or performing custom actions (such as user lifecycle operations).
For POST requests with no C param, set the C header to zero.

=head3 PUT

Used for replacing objects or collections. For PUT requests with no C param, set the C header to zero.

=head3 PATCH

Used for partially updating objects

=head3 DELETE

Used for deleting objects

=head2 IP ADDRESS

The public IP address of your application is automatically used as the client IP address for your request.
The API supports the standard C HTTP header to forward the originating client's IP address
if your application is behind a proxy server or acting as a sign-in portal or gateway.

B The public IP address of your trusted web application must be a part of the allowlist in your
org's network security settings as a trusted proxy to forward the user agent's original IP address
with the C HTTP header.

=head2 ERRORS

All successful requests return a 200 status if there is content to return or a 204 status
if there is no content to return.

All requests that result in an error return the appropriate 4xx or 5xx error code with a custom JSON
error object:

    {
      "code": "E0001",
      "error": "API validation failed",
      "status": false
    }

or

    {
      "code": "E0001",
      "message": "API validation failed",
      "status": false
    }

=over 4

=item code

A code that is associated with this error type

=item error

A natural language explanation of the error

=item message

A natural language explanation of the error (=error)

=item status

Any errors always return the status false

=back

List of codes see L

=head2 AUTHENTICATION

Suffit APIs support two authentication options: session and tokens.

The Suffit API requires the custom HTTP authentication scheme Token or Bearer for API token authentication.
Requests must have a valid API token specified in the HTTP Authorization header with the Token/Bearer
scheme or HTTP X-Token header.

For example:

    X-Token: 00QCjAl4MlV-WPXM...0HmjFx-vbGua
    Authorization: Token 00QCjAl4MlV-WPXM...0HmjFx-vbGua
    Authorization: Bearer 00QCjAl4MlV-WPXM...0HmjFx-vbGua

=head1 METHODS

This class inherits all methods from L and implements the following new ones

=head2 hint

    my $hint = $api->hint;
    my $hint = $api->hint('E1234');

Get hint by error code

=head2 ERROR CODES

List of common Suffit API error codes

=over 4

=item B -- General API error codes

B, B, B, B and B are reserved as HTTP errors

    API   | HTTP  | DESCRIPTION
   -------+-------+-------------------------------------------------
    E0000   [ * ]   Ok (general)
    E0100   [100]   Continue
    E0200   [200]   OK (HTTP)
    E0300   [300]   Multiple Choices
    E0400   [400]   Bad Request
    E0500   [500]   Internal Server Error

=item B -- Public API error codes

B - authentication and authorization Suffit API error codes.
See L for details

B - public Suffit API error codes.
See L for details

=item B -- Private API error codes

B - V1 Suffit API error codes.
See L for details

B - NoAPI Suffit API error codes.
See L for details

B - User profile Suffit API error codes.
See L for details

=item B -- Admin API error codes

B - Admin Suffit API error codes.
See L for details

=item B -- AuthDB error codes

B - AuthDB error codes.
See L for details

=item B -- Error codes are reserved for future use

=item B -- Error codes are reserved for future use

=item B -- Error codes are reserved for future use

=item B -- Error codes are reserved for future use

=item B -- Error codes are reserved for future use

=item B -- Error codes are reserved for future use

=item B -- Application error code

Error codes for user applications

=back

=head1 AUTHOR

Serż Minus (Sergey Lepenkov) L [e-mail]

=head1 COPYRIGHT

Copyright (C) 1998-2026 D&D Corporation

=head1 LICENSE

This program is distributed under the terms of the Artistic License Version 2.0

See the C file or L for details

=cut

our $VERSION = '1.06';

use Mojo::Base -base;

use Mojo::Loader qw/data_section/;
use Mojo::Util qw/trim/;

use WWW::Suffit::Cache;

has cache  => sub { WWW::Suffit::Cache->new };

sub hint {
    my $self = shift;
    my $name = shift || 'E0000';
    my @args = @_;
    my $cache = $self->cache;
    if (my $tpl = $cache->get($name)) {
        return trim($tpl) unless scalar @args;
        return trim(sprintf($tpl, @args));
    }
    my $tpl = data_section(__PACKAGE__, $name) // '';
    $cache->set($name => $tpl);
    return trim($tpl) unless scalar @args;
    return trim(sprintf($tpl, @args));
}

1;

__DATA__