README

An easy-to-use PHP client to access the One Community API.

Installation

composer require onecommunity/client

Usage

Initializing the Client

use OneCommunity\Client;

$apiKey = "xxxxxxx";
$projectName = "yourproject";
$userId = 1;

$client = new Client($apiKey, $userId, $projectName);

// Load private key from file..
$client->loadPrivateKey("private_rsa.pem");
// ..or string
$client->setPrivateKey($privateKey);

Sending Requests

See the Examples directory for working examples.

UserRequest

Returns the User object of the authenticated user. Great for testing.

use OneCommunity\Requests\UserRequest;

$request = new UserRequest;
$response = $client->send($request);

if ($response->isSuccessful()) {
    var_dump($response->getData());
}

SendTransactionalMailRequest

use OneCommunity\Requests\SendTransactionalMailRequest;

$accountId = 1; // Recipient
$transactionalMailId = 1; // Mail

$request = new SendTransactionalMailRequest($accountId, $transactionalMailId);
$request->setSubstitutions(['gift' => 'Free coffee ☕']);

$response = $client->send($request);

Responses

The following HTTP status codes are used:

HTTP Status Code	Description
200 OK	Everything is OK, the body contains the payload.
400 Bad Request	Indicates an authentication error.
404 Not Found	Some ID refers to an unknown model (e.g., unknown account or mail).
422 Unprocessable Entity	Validation errors.
429 Too Many Requests	You cannot send more than 60 requests per minute.

If anything unexpected occurs a OneCommunity\Exceptions\RequestException is thrown (e.g., if the API does not return a valid JSON response).

All responses (except 200 OK) contain a message attribute, explaining what went wrong. Furthermore, 400 Bad Requests responses contain a code attribute which can contain one of the following values:

code	message
100	Invalid API key
101	Could not decode Bearer token
102	No API key found on request
103	No Bearer token found on request
104	Token could not be verified
201	Client not found
202	User not found or not accessible by this API Client
501	No access to this project or invalid project
502	No access from this IP

The validation errors of a 422 Unprocessable Entity response are structured as follows:

{
    "errors": {
        "field1": [
            "error1",
            "error2"
        ],
        "field2": [
            "error3"
        ]
    }
}

Security

The API is based on JWT API, an efficient and secure machine-to-machine API using JSON Web Tokens and asymmetric request signing. Advantages of this approach include:

Requests and responses are sent over a secure channel.
Requests can only be signed by the API consumer (providing non-repudiation).
Requests are only valid for a short time (avoiding replay attacks).

Due to the asymmetric nature of this protocol, a public/private key pair needs to be generated (RSA 2048 bit). The key pair can be generated by issuing the following commands. Please send your public key (public_rsa.pem) to us and keep your private key safe.

Generating the Public/Private Key Pair

# Generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

# Generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem

onecommunity / client

Maintainers

Details