Here is the newest feature and this is one of the most innovative one. it is also the one before the last complex feature. This new feature intends to let you call any SOAP operation remotely really easily. In addition to ease any call to any SOAP operation, we used an actual and innovative way to achieve this: a REST Web service. Even if REST Web service is maybe a little bit misused in this case, it's mainly to get your attention on the fact that you'll deal with a REST Web service like it was one that handles ressources. Indeed, instead of having to develop sometimes tones of code to call a complex operation, you'll have now the possibility to call any operation using a simple URL.
For now, the REST Web service only accepts GET method. In addition, the only response format is for now JSON. We intend to support XML, PHP and JSONP, not necessarily in this order. The POST method will be implemented too. For example the POST method will allow you to override the request parameters before it's actually sent. Many other services will be added too.
In order to set this feature and to make it usable as easy as it could, it was necessary to use predefined requests. Otherwise, you would have had to define the whole request parameters each time which would have been very painful and heavy for you to implement. So, the solution to this issue was already there: use the saved requests. Using a saved request makes you save time a huge amount of time as you'll only have to indicate the saved request ID to use in order to send the request.
The REST Web service base URI
To call the REST Web service, you have to use this base URI:
- https://api.wsdltophp.com/rest/request/v1/send/[REST Api Token]/
Let's decompose this base URI :
- https: the protocol to use to call the Web service. It won't work on http
- api.wsdltophp.com: the unique domain used to call the REST Web service
- rest: our main service endpoint
- request: the type of service you want to use. For now only request exists. It matches all that corresponds to the requests things
- v1: the current REST Web service version
- send: the action used within the request service
- [REST Api Token]: you have to replace this whole string by yours. You can find your REST Api Token within your account dashboard in the Account information part
Given a token as 53d5dbf25871fddb417ca10105ee06ba2022f2a2, we would then have as base URI:
- https://api.wsdltophp.com/rest/request/v1/send/53d5dbf25871fddb417ca10105ee06ba2022f2a2/
Getting a response for a saved request
The GET method is usable any time you want to simply get the result of a saved request to an operation. In this case, a GET request to the REST Web service indicating the saved request ID will allow you to get the response to the saved request. The saved request is used to send an actual request to the SOAP Web service. The response you get is an instant response of the SOAP Web service and never a saved response.
To get the saved request ID, go the operation within the Execute tab within the package page. Then click on the Actions button to go to display the Load a request popin:
The saved request ID in this sample id 846.
The base URI to get the response of this saved request is:
- https://api.wsdltophp.com/rest/request/v1/send/[REST Api Token]/[Saved request ID][/Full][Format]
We won't explain the beginning of this URI as it has been done previously but let's clarify the last parameters:
- [Saved request ID]: this whole string has to be replaced by the saved request ID, 846 in our case
- [/Full]: this parameter controls the content of the REST Web service response. The Full value can be either /0, /1 or simply omited. If you set /1, then you'll get both the saved request meta data and the requests parameters.
- [Format]: the format has to be indicated using the dot and the name of the response format always placed at the end of the URI. For now only .json will work. As it is for now the only handled format, you can omit it. But to be sure it won't break later, we would advise you to always set it to .json from now.
So given the facts that our REST Api Token is 53d5dbf25871fddb417ca10105ee06ba2022f2a2, our saved request ID is 846, the URI can be:
- https://api.wsdltophp.com/rest/request/v1/send/53d5dbf25871fddb417ca10105ee06ba2022f2a2/846/1.json: you'll get the saved request details and the SOAP response
- https://api.wsdltophp.com/rest/request/v1/send/53d5dbf25871fddb417ca10105ee06ba2022f2a2/846.json: you'll only get the SOAP response
- https://api.wsdltophp.com/rest/request/v1/send/53d5dbf25871fddb417ca10105ee06ba2022f2a2/846/0.json: same as the previous one
Given the URI https://api.wsdltophp.com/rest/request/v1/send/53d5dbf25871fddb417ca10105ee06ba2022f2a2/846/1.json, here is below the JSON response we get:
{
"error_code":0,
"error":false,
"error_reason":null,
"output_format":"json",
"data": {
"soapcall": {
"id":"846",
"title":"Request sent on 13 February 2014 at 22h58m46s",
"description":"Call of PayPalServiceGet::GetBalance, nouvelle version PSR-2 de WsdlToPhp",
"created":"1392328700",
"packagename":"PayPal",
"servicename":"PayPalServiceGet",
"methodname":"GetBalance"
},
"requests": {
"soapoptions": {
"wsdl_url":"https:\/\/www.paypalobjects.com\/wsdl\/PayPalSvc.wsdl",
"location":"https:\/\/api-3t.paypal.com\/2.0\/"
},
"soapheaders": {
"namespace":{
"1":"urn:ebay:api:PayPalAPI"
},
"name": {
"1":"RequesterCredentials"
},
"mustunderstand": {
"1":"0"
},
"actor":{
"1":""
},
"data_type":{
"1":"PayPalStructCustomSecurityHeaderType"
},
"data":
{ "1":{
"1":"",
"2":"",
"3":{
"1":"",
"2":"",
"3":"",
"4":"***********************",
"5":"*********************",
"6":"***********************************************",
"7":"",
"8":""
}
}
}
},
"httpheaders": {
"name":[""],
"value":[""]
},
"parameters": {
"1":{
"1":{
"1":"1",
"2":"VALUE_RETURNALL",
"3":"",
"4":"109",
"5":""
}
}
}
},
"responses":{
"xmlrequest":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/\" xmlns:ns1=\"urn:ebay:apis:eBLBaseComponents\" xmlns:ns2=\"urn:ebay:api:PayPalAPI\">" +
" <SOAP-ENV:Header>" +
" <ns2:RequesterCredentials>" +
" <ns1:Credentials>" +
" <ns1:Username>******************************<\/ns1:Username>" +
" <ns1:Password>*************<\/ns1:Password>" +
" <ns1:Signature>***********************************<\/ns1:Signature>" +
" <\/ns1:Credentials>" +
" <\/ns2:RequesterCredentials>" +
" <\/SOAP-ENV:Header>" +
" <SOAP-ENV:Body>" +
" <ns2:GetBalanceReq>" +
" <ns2:GetBalanceRequest>" +
" <ns1:DetailLevel>ReturnAll<\/ns1:DetailLevel>" +
" <ns1:Version>109<\/ns1:Version>" +
" <ns2:ReturnAllCurrencies>1<\/ns2:ReturnAllCurrencies>" +
" <\/ns2:GetBalanceRequest>" +
" <\/ns2:GetBalanceReq>" +
" <\/SOAP-ENV:Body>" +
"<\/SOAP-ENV:Envelope>\n",
"xmlresponse":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http:\/\/schemas.xmlsoap.org\/soap\/envelope\/\" xmlns:SOAP-ENC=\"http:\/\/schemas.xmlsoap.org\/soap\/encoding\/\" xmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\" xmlns:xsd=\"http:\/\/www.w3.org\/2001\/XMLSchema\" xmlns:xs=\"http:\/\/www.w3.org\/2001\/XMLSchema\" xmlns:cc=\"urn:ebay:apis:CoreComponentTypes\" xmlns:wsu=\"http:\/\/schemas.xmlsoap.org\/ws\/2002\/07\/utility\" xmlns:saml=\"urn:oasis:names:tc:SAML:1.0:assertion\" xmlns:ds=\"http:\/\/www.w3.org\/2000\/09\/xmldsig#\" xmlns:wsse=\"http:\/\/schemas.xmlsoap.org\/ws\/2002\/12\/secext\" xmlns:ed=\"urn:ebay:apis:EnhancedDataTypes\" xmlns:ebl=\"urn:ebay:apis:eBLBaseComponents\" xmlns:ns=\"urn:ebay:api:PayPalAPI\">" +
" <SOAP-ENV:Header>" +
" <Security xmlns=\"http:\/\/schemas.xmlsoap.org\/ws\/2002\/12\/secext\" xsi:type=\"wsse:SecurityType\"\/>" +
" <RequesterCredentials xmlns=\"urn:ebay:api:PayPalAPI\" xsi:type=\"ebl:CustomSecurityHeaderType\">" +
" <Credentials xmlns=\"urn:ebay:apis:eBLBaseComponents\" xsi:type=\"ebl:UserIdPasswordType\">" +
" <Username xsi:type=\"xs:string\"\/>" +
" <Password xsi:type=\"xs:string\"\/>" +
" <Signature xsi:type=\"xs:string\"\/>" +
" <Subject xsi:type=\"xs:string\"\/>" +
" <\/Credentials>" +
" <\/RequesterCredentials>" +
" <\/SOAP-ENV:Header>" +
" <SOAP-ENV:Body id=\"_0\">" +
" <GetBalanceResponse xmlns=\"urn:ebay:api:PayPalAPI\">" +
" <Timestamp xmlns=\"urn:ebay:apis:eBLBaseComponents\">2014-03-25T19:30:21Z<\/Timestamp>" +
" <Ack xmlns=\"urn:ebay:apis:eBLBaseComponents\">Success<\/Ack>" +
" <CorrelationID xmlns=\"urn:ebay:apis:eBLBaseComponents\">f42394c06da52<\/CorrelationID>" +
" <Version xmlns=\"urn:ebay:apis:eBLBaseComponents\">109<\/Version>" +
" <Build xmlns=\"urn:ebay:apis:eBLBaseComponents\">9915774<\/Build>" +
" <Balance xsi:type=\"cc:BasicAmountType\" currencyID=\"EUR\">764.79<\/Balance>" +
" <BalanceTimeStamp xsi:type=\"xs:dateTime\">2014-03-25T19:30:21Z<\/BalanceTimeStamp>" +
" <BalanceHoldings xsi:type=\"cc:BasicAmountType\" currencyID=\"EUR\">764.79<\/BalanceHoldings>" +
" <\/GetBalanceResponse>" +
" <\/SOAP-ENV:Body>" +
"<\/SOAP-ENV:Envelope>\n",
"httpheaderrequest":{
"Host":"api-3t.paypal.com",
"Connection":"Keep-Alive",
"User-Agent":"PHP-SOAP\/5.3.5",
"Content-Type":"text\/xml; charset=utf-8",
"SOAPAction":"\"\"",
"Content-Length":"770"
},
"httpheaderresponse": {
"Date":"Tue, 25 Mar 2014 19:30:21 GMT",
"Server":"Apache",
"Content-Length":"1939",
"Connection":"close",
"Content-Type":"text\/xml; charset=utf-8"
},
"phprequest": [
{
"GetBalanceRequest":{
"ReturnAllCurrencies":"1",
"DetailLevel":"ReturnAll",
"ErrorLanguage":null,
"Version":"109",
"any":null
}
}
],
"phpresponse": {
"Balance": {
"currencyID":"EUR",
"_":"764.79"
},
"BalanceTimeStamp":"2014-03-25T19:30:21Z",
"BalanceHoldings": [
{
"currencyID":"EUR",
"_":"764.79"
}
],
"Timestamp":"2014-03-25T19:30:21Z",
"Ack":"Success",
"CorrelationID":"f42394c06da52",
"Errors":null,
"Version":"109",
"Build":"9915774"
},
"soapfault":""
}
}
}The soapcall and request attributes are populated as the /Full parameter is set to /1. Otherwise these two attributes would have been set to null.
The attributes that are always present are:
- error_code [int]: the code's error id if there is an error. If an error occurs, we're informed instantly. For now the error code can be one of:
- 0: no error
- 1: user unauthorized/unrecognized based on the REST Api Token
- 2: user account has been disabled
- 3: unable to log in user
- 4: internal error
- 5: saved request not found based on the saved request id you sent
- 6: internal exception
- error [bool]: true if an error occurred, false if no error occurred
- error_reason [string]: a human readable message that explains the error
- output_format [string]: the response's output format. It should match the Format parameter you indicated. If you did not indicated the Format, then it should be json
- data [object]: the actual data you have to handle
- soapcall [object]: the saved request meta data. Only populated if the /Full parameter is set to /1. Otherwise it is set to null
- requests [object]: the saved request parameters as we stored them. Only populated if the /Full parameter is set to /1. Otherwise it is set to null
- responses [object]: all the responses informations you can use. These informations are the same that are usually provided within the online web interface
Conclusion
As you can see, it is now very easy to call any operation as soon as you have saved the request. It should really ease you the calls to the SOAP Web service as you'll only have to call the URI.
This replaces the following steps by one step:
- downloading the package
- make sure your server settings are correct to send SOAP requests
- download the PHP request on your server
- execute the PHP request and call the various methods to get the response and identify the possible error
The only step you'll have to do now is:
- call the URL and handle the JSON response which contains all what you need
We're already working on the POST method to let you override any parameter contained by the saved request. Stay tuned!