WWW-Suffit-API
1 match

 view release on metacpan or  search on metacpan

lib/WWW/Suffit/API.pm  view on Meta::CPAN 

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<Content-Type>
and C<Accept> headers for every request as C<application/json>.

All Date objects are returned in L<ISO 8601|https://tools.ietf.org/html/rfc3339> format: C<YYYY-MM-DDTHH:mm:ss.SSSZ>
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<body> param, set the C<Content-Length> header to zero.

=head3 PUT

Used for replacing objects or collections. For PUT requests with no C<body> param, set the C<Content-Length> 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<X-Forwarded-For> 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<Note:> 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<X-Forwarded-For> 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<WWW::Suffit::API/"ERROR CODES">

=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



( run in 2.277 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )