REST Describe & Compile in practice
By Thomas Steiner. Written on . Work
Nothing helps you get a better feeling for your products than using them yourself. This can be a painful experience, or pure pleasure. Anyway, being an egomaniac guy, I am always interested in the readers of this blog. Loyal readers leave links, so I decided to give Yahoo's Inbound Links API a try. I navigated to the API's textual documentation, and based on the description created the following request URI:
http://search.yahooapis.com/SiteExplorerService/V1/inlinkData?
appid=YahooDemo&
query=https://blog.tomayac.com&
results=100&
start=1&
entire_site=1&
omit_inlinks=domain&
output=xml
I then fed this URI into REST Describe & Compile and hit the "Analyze" button.
The results were as follows:
 |
|
Custom types like the omit_links one cannot be detected from a client-side-only analysis as we would have to read the remote schema. This is not allowed because of the Same Origin Policy. However, we can safely treat these parameters as strings instead. The query parameter was mis-estimated to be xsd:anyURI. Well, it has a value of "https://blog.tomayac.com", so no big surprise. The API documentation states that this should be string, but come on, this API is about inbound links, so the target must be a URI, right? So no problem treating it like one.
The two results and start parameters were correctly identified as integers, however, the type for the latter parameter just being supposed. Why is this so? The response is the next parameter entire_site. This parameter actually is a boolean, however, the good folks at Yahoo use 1 instead of true as a value. REST Describe & Compile has this two-level type analysis feature mentioned earlier that in case of doubts also analyzes the parameter name. In none of the two cases the name starts with "is" or "has", or ends with "ed", which would be treated as boolean indicators. So the fallback is integer, however with just a "supposed" estimation quality rating. The two last parameters are custom types again, so nothing new to say.
According to the documentation, the API throws some standard 400, 403, and 503 errors. These "Faults" are quickly added to the WADL using the editor. We are interested in the <Result> elements of the response XML, so we add this as a "Representation". The result is the Yahoo! Inbound Links API WADL.
Next I hit the "Generate Code" button, then the "PHP 5" button, and out came PHP 5 code that I could directly use with the following script:
<?php
require_once('InlinkApi.php5');
$inlinkRequest = new InlinkDataRequest(
'MySecretYahooToken',
'https://blog.tomayac.com',
10,
1,
1,
'domain');
$response = $inlinkRequest->submit();
$xml = new SimpleXMLElement($response);
echo '<p>' . $xml['totalResultsAvailable'] . ' sites link to here.</p>';
foreach ($xml->Result as $result) {
echo '<p>' . $result->Title . ': <a href="' . $result->ClickUrl .
'">' . $result->Url . '</a></p>';
}
?>