Skip to content

Commit d276d7c

Browse files
author
Rowan Drew
committed
Fixes #6
Added classes to be able to call API endpoint to validate an organisation's security certificate, and show example on how to call the API endpoint. Additionally added minor fixes for error handling in API endpoints.
1 parent d193d2a commit d276d7c

6 files changed

+295
-19
lines changed

‎README.md

+105-16
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ If you are a software developer writing a PHP application then we recommend that
2929
* [Validate Organisation API Session Endpoint](#validate-organisation-api-session-endpoint)
3030
* [Validate/Create Organisation API Session Endpoint](#validatecreate-organisation-api-session-endpoint)
3131
* [Destroy Organisation API Session Endpoint](#destroy-organisation-api-session-endpoint)
32-
32+
* [Validate Organisation Security Certificate API Session Endpoint](#validate-organisation-security-certificate-api-session-endpoint)
33+
3334
## Getting Started
3435

3536
### Dependencies
@@ -124,7 +125,7 @@ Read [https://www.squizz.com/docs/squizz/Platform-API.html#section840](https://w
124125
?>
125126
```
126127

127-
## Retrieve Organisation Data Endpoint
128+
### Retrieve Organisation Data Endpoint
128129
The SQUIZZ.com platform's API has an endpoint that allows a variety of different types of data to be retrieved from another organisation stored on the platform.
129130
The organisational data that can be retrieved includes products, product stock quantities, and product pricing.
130131
The data retrieved can be used to allow an organisation to set additional information about products being bought or sold, as well as being used in many other ways.
@@ -915,13 +916,6 @@ The SQUIZZ.com platform's API will automatically expire and destory sessions tha
915916

916917
```php
917918
<?php
918-
/**
919-
* Copyright (C) 2017 Squizz PTY LTD
920-
* This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
921-
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
922-
* You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
923-
*/
924-
925919
//set automatic loader of the library's classes
926920
spl_autoload_register(function($className) {
927921
$className = ltrim($className, '\\');
@@ -1012,13 +1006,6 @@ Read [https://www.squizz.com/docs/squizz/Platform-API.html#section841](https://w
10121006

10131007
```php
10141008
<?php
1015-
/**
1016-
* Copyright (C) 2017 Squizz PTY LTD
1017-
* This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
1018-
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
1019-
* You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
1020-
*/
1021-
10221009
//set automatic loader of the library's classes
10231010
spl_autoload_register(function($className) {
10241011
$className = ltrim($className, '\\');
@@ -1099,3 +1086,105 @@ Read [https://www.squizz.com/docs/squizz/Platform-API.html#section841](https://w
10991086
echo "<div><b>$resultMessage</b><div><br/>";
11001087
?>
11011088
```
1089+
1090+
### Validate Organisation Security Certificate API Session Endpoint
1091+
1092+
The SQUIZZ.com platform's API has an endpoint that allows a TLS security certificate created for an organisation in the platform to be validated.
1093+
Before an organisation can download and use a security certificate the certificate must first be validated by a HTTP request calling this API endpoint.
1094+
The endpoint will check that the originating HTTP request's IP address matches the common name set for the certificate, or that a reverse DNS lookup matches the domain set in the certificate with the originating IP address of the endpoint request.
1095+
Read [https://www.squizz.com/docs/squizz/Platform-API.html#section842](https://www.squizz.com/docs/squizz/Platform-API.html#section843) for more documentation about the endpoint and its requirements.
1096+
See the example below on how the call the Validate Organisation Security Certificate endpoint. Note that a session must first be created in the API before calling the endpoint.
1097+
1098+
```php
1099+
<?php
1100+
//set automatic loader of the library's classes
1101+
spl_autoload_register(function($className) {
1102+
$className = ltrim($className, '\\');
1103+
$fileName = '';
1104+
$namespace = '';
1105+
if ($lastNsPos = strripos($className, '\\')) {
1106+
$namespace = substr($className, 0, $lastNsPos);
1107+
$className = substr($className, $lastNsPos + 1);
1108+
$fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
1109+
}
1110+
$fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
1111+
1112+
$apiNamespace = "squizz\\api\\v1";
1113+
$esdNamespace = "EcommerceStandardsDocuments";
1114+
$esdInstallPath = "/path/to/esd-php-library/src/";
1115+
1116+
//set absolute path to API php class files
1117+
if(substr($namespace, 0, strlen($apiNamespace)) === $apiNamespace){
1118+
$fileName = $_SERVER['DOCUMENT_ROOT']. '/src/' . $fileName;
1119+
}
1120+
//set absolute path to ESD library files
1121+
else if(substr($namespace, 0, strlen($esdNamespace)) === $esdNamespace){
1122+
$fileName = $esdInstallPath . $fileName;
1123+
}
1124+
1125+
require $fileName;
1126+
});
1127+
1128+
use squizz\api\v1\endpoint\APIv1EndpointResponse;
1129+
use squizz\api\v1\endpoint\APIv1EndpointOrgValidateSecurityCertificate;
1130+
use squizz\api\v1\APIv1OrgSession;
1131+
use squizz\api\v1\APIv1Constants;
1132+
1133+
1134+
//obtain or load in an organisation's API credentials, in this example from command line arguments
1135+
$orgID = $_GET["orgID"];
1136+
$orgAPIKey = $_GET["orgAPIKey"];
1137+
$orgAPIPass = $_GET["orgAPIPass"];
1138+
$orgSecurityCertificateID = $_GET["orgSecurityCertificateID"];
1139+
$sessionTimeoutMilliseconds = 20000;
1140+
1141+
echo "<div>Making a request to the SQUIZZ.com API</div><br/>";
1142+
1143+
//create an API session instance
1144+
$apiOrgSession = new APIv1OrgSession($orgID, $orgAPIKey, $orgAPIPass, $sessionTimeoutMilliseconds, APIv1Constants::SUPPORTED_LOCALES_EN_AU);
1145+
1146+
//call the platform's API to request that a session is created
1147+
$endpointResponse = $apiOrgSession->createOrgSession();
1148+
1149+
//check if the organisation's credentials were correct and that a session was created in the platform's API
1150+
$result = "FAIL";
1151+
$resultMessage = "";
1152+
if($endpointResponse->result == APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS)
1153+
{
1154+
}
1155+
else
1156+
{
1157+
//session failed to be created
1158+
$resultMessage = "API session failed to be created. Reason: " . $endpointResponse->result_message . " Error Code: " . $endpointResponse->result_code;
1159+
}
1160+
1161+
//if a session was successfully created then call API to validate a certificate with a given ID
1162+
if($apiOrgSession->sessionExists())
1163+
{
1164+
//give up on waiting for a response from the API after 30 seconds
1165+
$timeoutMilliseconds = 30000;
1166+
1167+
//call endpoint
1168+
$endpointResponseESD = APIv1EndpointOrgValidateSecurityCertificate::call($apiOrgSession, $timeoutMilliseconds, $orgSecurityCertificateID);
1169+
1170+
//check the result of validating the security certificate
1171+
if($endpointResponseESD->result == APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS){
1172+
$result = "SUCCESS";
1173+
$resultMessage = "Organisation security certificate has successfully been validated and activated.";
1174+
}else{
1175+
$result = "FAIL";
1176+
$resultMessage = "Organisation security certificate failed to validate. Reason: " . $endpointResponseESD->result_message . " Error Code: " . $endpointResponseESD->result_code . "<br/>";
1177+
}
1178+
}
1179+
1180+
//next steps
1181+
//call other API endpoints...
1182+
//destroy api session when done
1183+
$apiOrgSession->destroyOrgSession();
1184+
1185+
echo "<div>Result:<div>";
1186+
echo "<div><b>$result</b><div><br/>";
1187+
echo "<div>Message:<div>";
1188+
echo "<div><b>$resultMessage</b><div><br/>";
1189+
?>
1190+
```

‎src/squizz/api/v1/endpoint/APIv1EndpointOrgImportESDocument.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ public static function call($apiOrgSession, $endpointTimeoutMilliseconds, $impor
9292
{
9393
$endpointResponse->result = APIv1EndpointResponse::ENDPOINT_RESULT_FAILURE;
9494
$endpointResponse->result_code = APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_UNKNOWN;
95-
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . ex.getMessage();
95+
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . $ex.getMessage();
9696
}
9797

9898
return $endpointResponse;

‎src/squizz/api/v1/endpoint/APIv1EndpointOrgProcurePurchaseOrderFromSupplier.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ public static function call($apiOrgSession, $endpointTimeoutMilliseconds, $suppl
7474
{
7575
$endpointResponse->result = APIv1EndpointResponse::ENDPOINT_RESULT_FAILURE;
7676
$endpointResponse->result_code = APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_UNKNOWN;
77-
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . ex.getMessage();
77+
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . $ex.getMessage();
7878
}
7979

8080
return $endpointResponse;

‎src/squizz/api/v1/endpoint/APIv1EndpointOrgRetrieveESDocument.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ public static function call($apiOrgSession, $endpointTimeoutMilliseconds, $retri
104104
{
105105
$endpointResponse->result = APIv1EndpointResponse::ENDPOINT_RESULT_FAILURE;
106106
$endpointResponse->result_code = APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_UNKNOWN;
107-
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . ex.getMessage();
107+
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . $ex.getMessage();
108108
}
109109

110110
return $endpointResponse;

‎src/squizz/api/v1/endpoint/APIv1EndpointOrgValidateSecurityCertificate.php

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<?php
2+
/**
3+
* Copyright (C) 2017 Squizz PTY LTD
4+
* This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
5+
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
6+
* You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
7+
*/
8+
namespace squizz\api\v1\endpoint;
9+
require_once __DIR__ . '/../../../../../3rd-party/jsonmapper/JsonMapper.php';
10+
require_once __DIR__ . '/../../../../../3rd-party/jsonmapper/JsonMapper/Exception.php';
11+
12+
use squizz\api\v1\APIv1Constants;
13+
use squizz\api\v1\APIv1HTTPRequest;
14+
use squizz\api\v1\APIv1OrgSession;
15+
use squizz\api\v1\endpoint\APIv1EndpointResponseESD;
16+
use EcommerceStandardsDocuments\ESDocument;
17+
use EcommerceStandardsDocuments\ESDocumentConstants;
18+
use \JsonMapper;
19+
20+
/**
21+
* Class handles calling the SQUIZZ.com API endpoint for verifying a security certificate created for an organisation within the platform.
22+
* Security certificates are used to secure organisational data transferred across the Internet and computer networks
23+
*/
24+
class APIv1EndpointOrgValidateSecurityCertificate
25+
{
26+
/**
27+
* Calls the platform's API endpoint to validate the organisation's security certificate
28+
* The public Internet connection used to call the endpoint will be used to validate against the domain or IP address set for the security certificate
29+
* @param apiOrgSession APIv1OrgSession existing organisation API session
30+
* @param endpointTimeoutMilliseconds int amount of milliseconds to wait after calling the the API before giving up, set a positive number
31+
* @param orgSecurityCertificateID string ID of the orgnisation's security certificate in the platform
32+
* @return APIv1EndpointResponseESD response from calling the API endpoint
33+
*/
34+
public static function call($apiOrgSession, $endpointTimeoutMilliseconds, $orgSecurityCertificateID)
35+
{
36+
$endpointParams = "";
37+
$requestHeaders = array(APIv1HTTPRequest::HTTP_HEADER_CONTENT_TYPE . ": " . APIv1HTTPRequest::HTTP_HEADER_CONTENT_TYPE_FORM_URL_ENCODED);
38+
$endpointResponse = new APIv1EndpointResponseESD();
39+
40+
try{
41+
//set notification parameters
42+
$requestPostBody = "org_security_certificate_id=". urlencode(utf8_encode($orgSecurityCertificateID));
43+
44+
//set function used to read the response from the endpoint
45+
$endpointJSONReader = function($jsonArray, $endpointResponse){
46+
$endpointResponse->jsonDeserialize($jsonArray);
47+
return $endpointResponse;
48+
};
49+
50+
//make a HTTP request to the platform's API endpoint to validate the security certificate
51+
$endpointResponse = APIv1HTTPRequest::sendESDocumentHTTPRequest(APIv1Constants::HTTP_REQUEST_METHOD_POST, APIv1Constants::API_ORG_ENDPOINT_VALIDATE_CERT.APIv1Constants::API_PATH_SLASH.$apiOrgSession->getSessionID(), $endpointParams, $requestHeaders, $requestPostBody, null, $endpointTimeoutMilliseconds, $apiOrgSession->getSessionID(), $endpointJSONReader, $endpointResponse);
52+
53+
//check that the certificate was successfully validated
54+
if(strcasecmp($endpointResponse->result, APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS) != 0)
55+
{
56+
//check if the session still exists
57+
if(strcasecmp($endpointResponse->result, APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_SESSION_INVALID) != 0){
58+
//mark that the session has expired
59+
$apiOrgSession->markSessionExpired();
60+
}
61+
}
62+
}
63+
catch(Exception $ex)
64+
{
65+
$endpointResponse->result = APIv1EndpointResponse::ENDPOINT_RESULT_FAILURE;
66+
$endpointResponse->result_code = APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_UNKNOWN;
67+
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . $ex.getMessage();
68+
}
69+
70+
return $endpointResponse;
71+
}
72+
}
73+
?>

‎test/squizz/api/v1/example/APIv1ExampleRunnerValidateOrgSecurityCertificate.php

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<body style="font-family: sans-serif; background-color: #00a0e3; color: #FFF">
4+
<div style="text-align: center">
5+
<img src="http://www.squizz.com/ui/resources/images/logos/squizz_logo_mdpi.png"/>
6+
<hr style="max-width: 607px"/>
7+
<div>SQUIZZ Pty Ltd</div>
8+
<div>Testing SQUIZZ.com API PHP Library: version 1</div>
9+
<hr style="max-width: 607px"/>
10+
<h1>Validate Organisation Security Certificate Example</h1>
11+
<p>Tests making a request to the SQUIZZ.com API to create a session for an organisation, then makes a call to validate a security certificate that was created for an organisation.</p>
12+
<div style="max-width: 607px; background-color: #2b2b2b; color: #cacaca; text-align: center; margin: auto; padding-top: 15px;">
13+
<?php
14+
/**
15+
* Copyright (C) 2017 Squizz PTY LTD
16+
* This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
17+
* This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
18+
* You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
19+
*/
20+
21+
//set automatic loader of the library's classes
22+
spl_autoload_register(function($className) {
23+
$className = ltrim($className, '\\');
24+
$fileName = '';
25+
$namespace = '';
26+
if ($lastNsPos = strripos($className, '\\')) {
27+
$namespace = substr($className, 0, $lastNsPos);
28+
$className = substr($className, $lastNsPos + 1);
29+
$fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
30+
}
31+
$fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
32+
33+
$apiNamespace = "squizz\\api\\v1";
34+
$esdNamespace = "EcommerceStandardsDocuments";
35+
$esdInstallPath = "/path/to/esd-php-library/src/";
36+
37+
//set absolute path to API php class files
38+
if(substr($namespace, 0, strlen($apiNamespace)) === $apiNamespace){
39+
$fileName = $_SERVER['DOCUMENT_ROOT']. '/src/' . $fileName;
40+
}
41+
//set absolute path to ESD library files
42+
else if(substr($namespace, 0, strlen($esdNamespace)) === $esdNamespace){
43+
$fileName = $esdInstallPath . $fileName;
44+
}
45+
46+
require $fileName;
47+
});
48+
49+
use squizz\api\v1\endpoint\APIv1EndpointResponse;
50+
use squizz\api\v1\endpoint\APIv1EndpointOrgValidateSecurityCertificate;
51+
use squizz\api\v1\APIv1OrgSession;
52+
use squizz\api\v1\APIv1Constants;
53+
54+
55+
//obtain or load in an organisation's API credentials, in this example from command line arguments
56+
$orgID = $_GET["orgID"];
57+
$orgAPIKey = $_GET["orgAPIKey"];
58+
$orgAPIPass = $_GET["orgAPIPass"];
59+
$orgSecurityCertificateID = $_GET["orgSecurityCertificateID"];
60+
$sessionTimeoutMilliseconds = 20000;
61+
62+
echo "<div>Making a request to the SQUIZZ.com API</div><br/>";
63+
64+
//create an API session instance
65+
$apiOrgSession = new APIv1OrgSession($orgID, $orgAPIKey, $orgAPIPass, $sessionTimeoutMilliseconds, APIv1Constants::SUPPORTED_LOCALES_EN_AU);
66+
67+
//call the platform's API to request that a session is created
68+
$endpointResponse = $apiOrgSession->createOrgSession();
69+
70+
//check if the organisation's credentials were correct and that a session was created in the platform's API
71+
$result = "FAIL";
72+
$resultMessage = "";
73+
if($endpointResponse->result == APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS)
74+
{
75+
}
76+
else
77+
{
78+
//session failed to be created
79+
$resultMessage = "API session failed to be created. Reason: " . $endpointResponse->result_message . " Error Code: " . $endpointResponse->result_code;
80+
}
81+
82+
//if a session was successfully created then call API to validate a certificate with a given ID
83+
if($apiOrgSession->sessionExists())
84+
{
85+
//give up on waiting for a response from the API after 30 seconds
86+
$timeoutMilliseconds = 30000;
87+
88+
//call endpoint
89+
$endpointResponseESD = APIv1EndpointOrgValidateSecurityCertificate::call($apiOrgSession, $timeoutMilliseconds, $orgSecurityCertificateID);
90+
91+
//check the result of validating the security certificate
92+
if($endpointResponseESD->result == APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS){
93+
$result = "SUCCESS";
94+
$resultMessage = "Organisation security certificate has successfully been validated and activated.";
95+
}else{
96+
$result = "FAIL";
97+
$resultMessage = "Organisation security certificate failed to validate. Reason: " . $endpointResponseESD->result_message . " Error Code: " . $endpointResponseESD->result_code . "<br/>";
98+
}
99+
}
100+
101+
//next steps
102+
//call other API endpoints...
103+
//destroy api session when done
104+
$apiOrgSession->destroyOrgSession();
105+
106+
echo "<div>Result:<div>";
107+
echo "<div><b>$result</b><div><br/>";
108+
echo "<div>Message:<div>";
109+
echo "<div><b>$resultMessage</b><div><br/>";
110+
?>
111+
</div>
112+
</div>
113+
</body>
114+
</html>

0 commit comments

Comments
 (0)