Access One Community from PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
src
.gitignore Import code. May 29, 2018
LICENSE
README.md Update README.md Oct 23, 2018
composer.json Account, ValidateAccountCredentials, AddInteractions, Interactions Oct 22, 2018

README.md

One Community

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

Installation

Using Composer:

composer require onecommunity/client

Contact us with your public key to receive your API key.

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