A Look Inside the Think Tank...

REST Describe & Compile in practice

Created on and categorized as Work.
Written by Thomas Steiner.

REST Describe & Compile in practice

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=http://blog.tomayac.de&
  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:


  • appid xsd:string (supposed) » Estimation: true. Missing: parameter is required.
  • query xsd:anyURI (sure) » Estimation: false. This is a string. Missing: parameter is required.
  • results xsd:integer (sure) » Estimation: true. Missing: default is 50.
  • start xsd:integer (supposed) » Estimation: true. Missing: default is 1.
  • entire_site xsd:string (supposed) » Estimation: true/false. Parameter is 1 or no value.
  • omit_inlinks xsd:string (supposed) » Estimation: false. This is one out of {none|domain|subdoamin}. Missing: default is none.
  • output xsd:string (supposed) » Estimation: false. This is one out of {xml|json|php}. Missing: default is xml.
So all in all, the estimation rate is far from being perfect. The good news is: this does not matter much :-)

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 "http://blog.tomayac.de", 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',
'http://blog.tomayac.de',
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>';
}
?>
I did not have to change anything in the generated code. Try it out on your own: take my previously generated WADL, upload it to REST Describe & Compile and generate your own code. As a prove that I did not lie to you check out my code directly from here. Not so bad. What do you say?