README

A PHP SDK for interacting with the Macloud API. This SDK provides a simple and secure way to make RESTful API requests with built-in signature authentication.

Features

• Support for GET, POST, PATCH, PUT, and DELETE HTTP methods
• Built-in SHA256 signature authentication
• RESTful API design
• JSON request/response format
• Configurable timeout settings
• Optional logging support

Requirements

• PHP >= 5.5
• Composer

Installation

Install the package via Composer:

composer require macloudapisdk/sdk

Configuration

Before using the SDK, you need to obtain the following credentials:

• app_id: Your application ID (contact technical support to register an account and apply for API credentials)
• app_secret: Your application secret key (used for signature generation)
• base_api_url: The base API URL (e.g., http://api.local.com/V4/). Contact operations staff for the specific address.

Configuration Parameters

Usage

Basic Setup

error_reporting(E_ALL);
ini_set('display_errors', 'on');

require './vendor/autoload.php';

try {
    $config = [
        'app_id'       => getenv('SDK_APP_ID'),
        'app_secret'   => getenv('SDK_APP_SECRET'),
        'base_api_url' => getenv('SDK_API_PRE'),
        // 'log'          => true,           // Enable SDK logging
        // 'logfileLinux' => '/tmp/sdk.log', // Linux log file path
    ];
    $sdk = new \macloudapisdk\Sdk($config);
    
    // Your API calls here...
    
} catch(\Exception $e) {
    var_dump("code: " . $e->getCode() . " message: " . $e->getMessage());
}

GET Request

$request = [
    'url' => 'test.sdk.get',
    'query' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
    'body' => [],
];
$result = $sdk->get($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

POST Request

$request = [
    'url' => 'test.sdk.post',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->post($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

PATCH Request

$request = [
    'url' => 'test.sdk.patch',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->patch($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

PUT Request

$request = [
    'url' => 'test.sdk.put',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->put($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

DELETE Request

$request = [
    'url' => 'test.sdk.delete',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->delete($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);

Signature Algorithm

The SDK uses SHA256 signature authentication to ensure data integrity during transmission:

• Client-side: Uses SHA256 algorithm to sign the base64-encoded parameters combined with app_secret. Each request includes the signature.
• Server-side: Uses the same algorithm to sign the received parameters and compares it with the provided signature to verify authenticity.

This ensures that data cannot be tampered with during transmission.

Important Notes

1. URI and Query Parameters: For all requests, URI and GET parameters are separated. For example, if the URL is https://api.local.com/V4/version?v=1, the v=1 parameter must be passed through the query parameter in the request array.

2. Return Value: Each API call returns a raw string response. You can decode it using json_decode() to get the parsed JSON data.

3. Error Handling: Always wrap SDK calls in try-catch blocks to handle exceptions properly.

API Response Format

The SDK returns the raw response string. The API typically returns JSON format, which can be decoded using json_decode($result, true) to get an associative array.

Support

For API credentials and base URL information, please contact:

• Technical Support: For app_id and app_secret registration
• Operations Staff: For the specific API base URL