vdata

JavaScript client of VDATA protocol. VDATA protocol is the best protocol for calling or responding a HTTP/HTTPS service.

Usage no npm install needed!

<script type="module">
  import vdata from 'https://cdn.skypack.dev/vdata';
</script>

README

vdata

VDATA protocol is the best protocol for calling or responding a HTTP/HTTPS service.

Features

  • Defines the data protocol for HTTP/HTTPS based service Remote Process Call.
  • Defines common error codes and the range of user customized error codes.
  • Defines common status codes.
  • RESTfull api supported.
  • Cross-Origin Resource Sharing supported.
  • Send version request by HTTP_ACCEPT from client.
  • Respond in-service version of service from server.

Data Protocol/Format

{
    "name"			: "",		//	string,	name of service
    "url"			: "",		//	string,	address of service
    "version"		: "1.0",	//	string,	version of service
    "errorid"		: 0,		//	numeric,	error id
    "errordesc"		: "",		//	string,	desciption of error
    "parents"		: {},		//	array,	parent nodes
    "vdata"			: {}		//	user customized data. it might be a string, number, array or an object
}

Comnon error codes

error defines error code remark
ERROR_SUCCESS 0 successfully
ERROR_UNKNOWN -100000 unknown errors
ERROR_ACCESS_DENIED -100001 access denied
ERROR_PARAMETER -100002 error in parameters
ERROR_PERMISSION -100003 error in permission
ERROR_EXPIRED -100004 error in expired
ERROR_NOT_LOGGEDIN -100005 error in not logged in
ERROR_FAILED_LOGGEDIN -100006 error in failed logged in
ERROR_CREATE_INSTANCE -100010 error in creating instance
ERROR_EXCEPTION -100011 error in exception
ERROR_DB_SELECT -100050 error in selecting database
ERROR_DB_UPDATE -100051 error in updating database
ERROR_DB_INSERT -100052 error in inserting database
ERROR_DB_DELETE -100053 error in deleting database
ERROR_DB_DROP -100054 error in dropping database
ERROR_DB_TRANSACTION -100060 error in transaction
ERROR_DB_TABLE_NAME -100065 error in table name
ERROR_REQUEST_VIA_IP -100100 bad request via ip request
ERROR_MO_NOT_ENOUGH_COINS -100200 not enough coins
ERROR_MO_HIRE_OVERDUE -100201 the hiring date is overdue
ERROR_MO_TRANSACTION_TYPE -100202 error consume type
ERROR_NETWORK -100300 error network
ERROR_JSON -100301 error json
ERROR_JSON_ERRORID -100302 error json.errorid
ERROR_JSON_ERRORDESC -100303 error json.errordesc
ERROR_JSON_VDATA -100304 error json.vdata

the range of user customized error codes

error defines error code remark
ERROR_USER_START 10000 start of user customized error id
ERROR_USER_END 99999 end of user customized error id

Cross-Origin Resource Sharing

use dekuan\vdata\CResponse;


$cResponse	= CResponse::GetInstance();

//
//	requests from *.domain1.com will be allowed
//
$cResponse->SetCorsDomains( [ '.domain1.com' ] );

//	...

Send Request to Server

1, Send GET request and receive VData response

use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest	= CRequest::GetInstance();
$arrResponse	= [];
$nCall		= $cRequest->Get
(
    [
        'url'		=> 'http://api-account.yunkuan.org/api/login',
        'data'		=>
        [
            'u_name'	=> 'username',
            'u_pwd'		=> 'password',
            'u_keep'	=> 1
        ],
        'version'	=> '1.0',
        'timeout'	=> 30,		//	timeout in seconds
        'cookie'	=> [],		//	array or string are both okay.
        'headers'	=> [],
    ],
    $arrResponse
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidVData( $arrResponse ) )
{
    //	arrResponse
    //		'errorid'	: error id
    //		'errordesc'	: error desc
    //		'vdata'		: virtual data
    //		'version'	: version of service
    //		'json'		: original json array
    print_r( $arrResponse );
}

2, Send POST request and receive VData response

use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest	= CRequest::GetInstance();
$arrResponse	= [];
$nCall		= $cRequest->Post
(
    [
        'url'		=> 'http://api-account.yunkuan.org/api/login',
        'data'		=>
        [
            'u_name'	=> 'username',
            'u_pwd'		=> 'password',
            'u_keep'	=> 1
        ],
        'version'	=> '1.0',
        'timeout'	=> 30,		//	timeout in seconds
        'cookie'	=> [],		//	array or string are both okay.
        'headers'	=> [],
    ],
    $arrResponse
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidVData( $arrResponse ) )
{
    //	arrResponse
    //		'errorid'	: error id
    //		'errordesc'	: error desc
    //		'vdata'		: virtual data
    //		'version'	: version of service
    //		'json'		: original json array
    print_r( $arrResponse );
}

3, Send GET/POST request and receive Raw response

use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest	= CRequest::GetInstance();
$arrResponse	= [];
$nCall		= $cRequest->HttpRaw
(
    [
        'method'	=> 'POST',	//	'GET' / 'POST'
        'url'		=> 'http://api-account.yunkuan.org/api/login',
        'data'		=>
        [
            'u_name'	=> 'username',
            'u_pwd'		=> 'password',
            'u_keep'	=> 1
        ],
        'version'	=> '1.0',
        'timeout'	=> 30,		//	timeout in seconds
        'cookie'	=> [],		//	array or string are both okay.
        'headers'	=> [],
    ],
    $arrResponse
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidRawResponse( $arrResponse ) )
{
    //	arrResponse	- Array
    //		'data'		: http data
    //		'status'	: status code
    //		'headers'	: response headers
    print_r( $arrResponse );
}

Respond to Client

1, Respond by json encoded string

use dekuan\vdata\CResponse;


$cResponse	= CResponse::GetInstance();

$cResponse->SetServiceName( 'Test of responding array VData' );
$cResponse->SetServiceUrl( 'http://www.ladep.cn/' );
$arrVData	= $cResponse->GetVDataString
(
    0,
    "error desc",
    [ "info" => "User customized info" ],
    $cResponse->GetDefaultVersion()
);

echo( $arrVData );

2, Respond by json array

use dekuan\vdata\CResponse;


$cResponse	= CResponse::GetInstance();

$cResponse->SetServiceName( 'Test of responding array VData' );
$cResponse->SetServiceUrl( 'http://www.ladep.cn/' );
$arrVData	= $cResponse->GetVDataArray
(
    0,
    "error desc",
    [ "info" => "User customized info" ],
    $cResponse->GetDefaultVersion()
);

print_r( $arrVData );

3, Respond by Laravel response instance

use dekuan\vdata\CResponse;


$cResponse	= CResponse::GetInstance();

$cResponse->SetServiceName( 'Test of responding array VData' );
$cResponse->SetServiceUrl( 'http://www.ladep.cn/' );
$nCall	= $cResponse->Send
(
    0,
    "error desc",
    [ "info" => "User customized info" ],
    $cResponse->GetDefaultVersion()
);

Testing


mocha tests/js/index.test.js