An easy-to-use PHP client to access the One Community API., (*1)
Installation
Using Composer:, (*2)
composer require onecommunity/client, (*3)
Contact us with your public key to receive your API key., (*4)
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., (*5)
UserRequest
Returns the User object of the authenticated user. Great for testing., (*6)
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:, (*7)
| 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)., (*8)
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:, (*9)
| 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:, (*10)
{
"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:, (*11)
- 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., (*12)
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
Wallogit.com
