New methods have been added to our REST API, check it out!

  24 avril 2014       Cet article a 0 commentaire       De Mikaël DELSOL

A REST Api has to be flexible and capable of evolving over the time. Moreover, it must evolve according to the features it already provides in order to keep its homogeneity and its flexibility. We're still in the beginning of our Api so it should evolve for a long time in the future. As we only provided GET method until now, we now provide the first POST method. We hope to fit your needs. If not, feel free to post a comment at the bottom or to send us a mesage.

Our REST Api has been recently evolved. It now allows to:

  • GET a saved request: this means that you can get the saved data of a request. This allows you to to learn how data are structured.
  • POST a request: until now you were only able to get the result of a request using the saved request and the GET method. From now, using the POST method, you can override each saved parameter used to send the request before the SOAP request is actually sent.

Before going further, if you haven't already read them, please read the two first posts about our REST Api:

Get a saved request

Getting a saved request is one of the easiest method. Its main goal is to let you get the exact data structures to use for the next method we'll describe after. All you need is your REST Api Token and the saved request ID.

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:

Get the saved request ID - WSDL to php

The saved request ID in this sample id 846.

The base URI to GET the response of this saved request is:

  •[REST Api Token]/[Saved request ID][Format]

We won't explain the beginning of this URI as it has been done previously but let's clarify the last parameters:

  1. [Saved request ID]: this whole string has to be replaced by the saved request id, 846 in our case
  2. [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. Possible values:
    • .json
    • .php
    • .jsonp
    • .xml

In this case we would advise to use one of json and php format as you can easily handle them using either JavaScript or PHP (using unserialize).

So given the fact that our REST Api Token is 53d5dbf25871fddb417ca10105ee06ba2022f2a2, our saved request ID is 846, the URI can be:

  • you'll get the saved request details as json
  • you'll get the saved request details as php

Just to give you an example of the data you'll get, here they are.

JSON format:

{ "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:\/\/\/wsdl\/PayPalSvc.wsdl", "location":"https:\/\/\/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":"" } } } } } }

PHP format:

a:5:{ s:10:"error_code";i:0; s:5:"error";b:0; s:12:"error_reason";N; s:13:"output_format";s:3:"php"; s:4:"data";a:2:{ s:8:"soapcall";a:7:{ s:2:"id";s:3:"846"; s:5:"title";s:45:"Request sent on 13 February 2014 at 22h58m46s"; s:11:"description";s:73:"Call of PayPalServiceGet::GetBalance, nouvelle version PSR-2 de WsdlToPhp"; s:7:"created";s:10:"1392328700"; s:11:"packagename";s:6:"PayPal"; s:11:"servicename";s:16:"PayPalServiceGet"; s:10:"methodname";s:10:"GetBalance"; } s:8:"requests";a:4:{ s:11:"soapoptions";a:2:{ s:8:"wsdl_url";s:49:""; s:8:"location";s:30:""; } s:11:"soapheaders";a:6:{ s:9:"namespace";a:1:{ i:1;s:22:"urn:ebay:api:PayPalAPI"; } s:4:"name";a:1:{ i:1;s:20:"RequesterCredentials"; } s:14:"mustunderstand";a:1:{ i:1;s:1:"0"; } s:5:"actor";a:1:{ i:1;s:0:""; } s:9:"data_type";a:1:{ i:1;s:36:"PayPalStructCustomSecurityHeaderType"; } s:4:"data";a:1:{ i:1;a:3:{ i:1;s:0:""; i:2;s:0:""; i:3;a:8:{ i:1;s:0:""; i:2;s:0:""; i:3;s:0:""; i:4;s:26:"*******************************"; i:5;s:16:"*******************************"; i:6;s:56:"**************************************************************"; i:7;s:0:""; i:8;s:0:""; } } } } s:11:"httpheaders";a:2:{ s:4:"name";a:1:{ i:0;s:0:""; } s:5:"value";a:1:{ i:0;s:0:""; } } s:10:"parameters";a:1:{ i:1;a:1:{ i:1;a:5:{ i:1;s:1:"1"; i:2;s:15:"VALUE_RETURNALL"; i:3;s:0:""; i:4;s:3:"109"; i:5;s:0:""; } } } } } }

XML format:

<?xml version="1.0" encoding="UTF-8"?> <xml formated="false"> <error_code>0</error_code> <error></error> <error_reason /> <output_format>xml</output_format> <data> <soapcall> <id>846</id> <title>Request sent on 13 February 2014 at 22h58m46s</title> <description>Call of PayPalServiceGet::GetBalance, nouvelle version PSR-2 de WsdlToPhp</description> <created>1392328700</created> <packagename>PayPal</packagename> <servicename>PayPalServiceGet</servicename> <methodname>GetBalance</methodname> </soapcall> <requests> <soapoptions> <wsdl_url></wsdl_url> <location></location> </soapoptions> <soapheaders> <namespace> <array_element index="1">urn:ebay:api:PayPalAPI</array_element> </namespace> <name> <array_element index="1">RequesterCredentials</array_element> </name> <mustunderstand> <array_element index="1">0</array_element> </mustunderstand> <actor> <array_element index="1"></array_element> </actor> <data_type> <array_element index="1">PayPalStructCustomSecurityHeaderType</array_element> </data_type> <data> <array_element index="1"> <array_element index="1"></array_element> <array_element index="2"></array_element> <array_element index="3"> <array_element index="1"></array_element> <array_element index="2"></array_element> <array_element index="3"></array_element> <array_element index="4">*******************************</array_element> <array_element index="5">*******************************</array_element> <array_element index="6">**************************************************************</array_element> <array_element index="7"></array_element> <array_element index="8"></array_element> </array_element> </array_element> </data> </soapheaders> <httpheaders> <name> <array_element index="0"></array_element> </name> <value> <array_element index="0"></array_element> </value> </httpheaders> <parameters> <array_element index="1"> <array_element index="1"> <array_element index="1">1</array_element> <array_element index="2">VALUE_RETURNALL</array_element> <array_element index="3"></array_element> <array_element index="4">109</array_element> <array_element index="5"></array_element> </array_element> </array_element> </parameters> </requests> </data> </xml>

Each of them is not as indented as it is shown above but "compressed" as the smallest content as it is possible.

POST a request

Here is an interesting method. It allows you to use a saved request and to override any saved parameter before it is actually used to send the SOAP request. This means that you can actually create request templates/squeletons with default values. Then you can use the saved request and only modify let's say the page number or the offset if there is one. The main goal is to let you call easily any of the provided SOAP operation and modify any value as easily as possible.

Be aware that only saved parameters, present in the GET the saved request result, can be overriden. You can't add any additional parameter and value.

The base URI to POST a request is the same as you use to send a request but using POST method:

  •[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:

  1. [Saved request ID]: this whole string has to be replaced by the saved request id, 846 in our case
  2. [/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.
  3. [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. Possible values:
    • .json
    • .php
    • .jsonp
    • .xml

In addition to that, you must send at least one parameter value to override it. In order to do that, you have to use the same data structure you've got from the GET a saved request method. Concretely, you have to use one of the following parameter:

  • soapoptions: the SoapClient options
  • soapheaders: the SoapClient Headers
  • httpheaders: the SoapClient HTTP Headers
  • parameters: the request parameters

Each parameter value must fit the previously showned arrays. Not each value has to be present but you must strictly use the same keys otherwise it won't work. You must also notice from the previous samples that any class constant value must be indicated using the constant name and not its corresponding value.

Here is how we do it programmativally using the HttpRequest class:

$posts = array( 'parameters'=>array( 1=>array( 1=>array( 4=>112))), 'soapheaders'=>array( 'mustunderstand'=>array( 1=>1)), 'soapoptions'=>array( 'wsdl_url'=>__DIR__ . '/../../wsdl/112.0/PayPalSvc.wsdl'), 'httpheaders'=>array( 'name'=>array( 'X-FROM', 'X-TO'), 'value'=>array( 'ME', 'YOU'))); $url = ''; $http = new HttpRequest($url,HTTP_METH_POST); $http->setPostFields($posts); $data = $http->send(); print_r(unserialize($data->body));

In this example, we:

  • override the PayPal API version parameter value
  • set the SoapClient Header mustunderstand parameter to 1
  • use a local WSDL file
  • try to set two HTTP Headers, X-FROM and X-TO, but only the first one will be used as the saved request defines only one HTTP Header entry

And that's it! Using this POST method now gives you more flexibility and usability than only the GET method.

Keep in touch for the next methods.