My Guidelines for designing a restful APIs so frontend devs won't ask where I live

As a backend developer, I have to play nice with the frontend people. Let's face it, I don't want to be prison shanked on the lunch line. Easier said than done because of the different ideas that people have floated around like these three.

• JSON:API
• OpenAPI
• GraphQL

Each one of these have pros and cons but those are academic papers that I don't care to write right now. But I've worked and talked to a lot of frontend devs and they don't really care if we use any of the three examples that I gave. 

For them, a good API:

1. Is well documented - makes sense; I'm a fan of drfdocs. Also Swagger gets a lot of mentions.
2. Is versioned - good point; because changes to existing ones break too many things
3. Is idempotent - to be honest I had to look this one up but it's the same idea of pure functions. Given the same input, it should return the same value (output)
4. Uses HTTP errors correctly - For example, don't return errors with 200 status. Oops.
5. Uses HTTP verbs sensibly - they want none of that 'GET /v1.0/delete/100' because that shit is stupid.
6. Is NOT SOAP - dear lord up above in heaven, not ever SOAP. Ever

I also don't like SOAP. 

Being stupid while calling Twitter's Search API

A few days ago, I just figured out how to authenticate my Ionic app using Twitter's application-only Oauth. Application only authentication allows you call Twitter APIs without that Twitter login screen.

The being stupid part started when I tried using the Search API.

    var twitterStreamURL = "https://api.twitter.com/1.1/search/tweets.json?q="; 
    var qValue = "queryString";
    var numberOfTweets = "&count=10";

It should be easy to see that to call the Search API you'll concatinate the qValue (or query string) and the numberOfTweets (number of tweets to get) to the twitterStreamURL. You'd do then a ajax call then get the resulting JSON.

    
    var cURL = "https://api.twitter.com/1.1/search/tweets.json?q=" + qvalue + numberOfTweets; 

These would be no problem with the query string had only one value or no special characters. This stumped me a bit because I used escape() function at first which I knew about. It still works but the escape() function is deprecated. Which lead me to encodeURI(). It worked until it was asked to search for strings with hash tags. I didn't read the fine print for encodeURI which said it doesn't encode certain special characters. This finally lead me to the encodeURIComponent() function.

    
    var cURL = "https://api.twitter.com/1.1/search/tweets.json?q=" + encodeURIComponent(qvalue) + numberOfTweets; 

The moral of this story is I need read the fine print.

Winamp, a threat, a petition, AngularJS and shit is about to get real

A few days ago, I made a threat that I will remove people from the CDO-ITG group page if they didn't sign a certain petition. I said that I was doing to remove every shit on this group who didn't sign the Winamp petition and I said that I will know who didn't sign. Everyone laughed. Not. fucking. anymore.

Change.org has an API that allows me get at all of the signatures in the Winamp petition. Although, Change.org's API isn't quite mature, it's usable and quite easy to use with AngularJS. Here is a snippet:

wapp.factory('changeOrgService', function($resource){

    var _changeOrg = {};
    
    _changeOrg.getSignatures = function(petitionId){
        var baseUrl = 'https://api.change.org/v1/petitions';
        return $resource(baseUrl + '/:id/signatures?api_key=' + winampPapp.api_key + "&callback=JSON_CALLBACK",{id: petitionId}, 
            { get: { method: 'JSONP', params: { page: 1} }});
    };

    _changeOrg.getPetitionId = function(url){
        var baseUrl = 'http://api.change.org/v1/petitions/get_id';
        return $resource(baseUrl, {},
            { get: {method: 'JSONP'}, params:{api_key: winampPapp.api_key, petition_url: url, callback: 'JSON_CALLBACK'}});
    };

    return _changeOrg;
});

That should be easy to figure since its only a pretty simple AngularJS factory that depends on the ngResource module to get at the data. Add underscore and then you can do something interesting with the petition signature data like figure out how many signed from the Philippines (26), how many are from the Cagayan de Oro (DO YOU WANT TO FUCKING KNOW?! DO YOU?).

Now, how about REALLY signing that petition before I really do something crazy like find out where you live.

When we need something more than Firebug

Us web developers in our quest to build something unique will eventually come upon a wall that looks insurmountable with our current set of debugging tools like Firebug and Chrome's or IE's developer tools. Sometimes you just need something that can work at the HTTP protocol. This is where Fiddler2 comes in. Fiddler is a web debugging proxy for any browser, system or platform. Which makes it quite handy if you're doing AJAX stuff on a lot of different platforms from Java to Node.js.

What's really special with Fiddler is the composer feature which allows to make AJAX verb (GET, DELETE, PUT, HEAD, etc.) calls to your server side API. It then allows you to look at the response headers, cookies, the raw results and a bunch of other values to help you debugged that code.

Use this with Mozilla Firefox to get the most mileage out of it since it does integrate into it quite nicely. Chrome doesn't do it because of that new rule that you can't install a plugin that's not found in the Chrome store.

It also has a nice set of add-ons which is just icing on cake. I like StresStimulus add-on which allows you to do load testing with your web apps.

Another thing is this thing is free and will run on Linux boxes (needs Mono though).

Add this to your toolbox.

Overcoming the same-origin policy in AJAX/JS programming

If you are serious with AJAX (and/or JavaScript) then you probably ran into the same-origin policy. The policy is an important security concept and SHOULD NOT be turned off. But like everything else on the web, it cramps programming or limits system designs and overcoming it is a mess of kludges and dirty hacks. Enter CORS.

Cross-Origin Resource Sharing (CORS) is a specification that allows you to implement cross-domain request (ie. use an AJAX resource from another domain). The spec defines a set of headers that allow the browser and server to communicate about which request are (and are not) allowed. It isn't that hard and its supported by all browsers (it even works on IE8, which is down-right surprising).

For example, Adding CORS on an Apache server is just:

headtroll@trollmachine:/# a2enmod headers

And then to expose the header, you simply add the following to your Apache .conf file:

Header set Access-Control-Allow-Origin "*"

More details here.

As for the client side, HTML5Rocks.com already has a tutorial on how to use CORS.

DAT Angular

This is part 5 of my Resteasy Tapestry with AngularJS tutorial. This is last part of the tutorial where you combine both. You should end up with a Resteasy-Tapestry5 server with the Ajax APIs and a second web application that uses the APIs via AngularJS. 

Using Ajax APIs with AngularJS is easy if you use Angular-Resource. Angular-Resource is not a default add-on for AngularJS. You don't have to download it since Google's CDNs also serve it.

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular.min.js"></script>  
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular-resource.js"></script>  
<script type="text/javascript" src="js/tangled.js"></script>  

The tangled.js script there is where we write the interesting parts. Here's a partial of that script:

angular.module('tangled-app',['ngResource'])
    .controller('tangledCtrl', function($scope, $resource){
        var Customer = $resource('http://localhost\\:8080/tangled/rest/customers');
        
        $scope.appName = "Tangled App";             // App name
        $scope.customers = Customer.query();        // Calls our Resteasy-Tapestry REST API /GET customers
    })
........

The script basically just means that I'm working with a Angular app called "tangled-app" and then AngularJS inits to also load the Angular-Resource library so we can use the $resource variable. The whole thing then just hinges on the var Customer = $resource('http://localhost\\:8080/tangled/rest/customers'); line. Think of this line as a "promise", it promises to return data when you call the query or equivalent function.

After the script all you have to do is add the tangled-app value to the ng-app directive and the tangledCtrl to a ng-controller:

 <!DOCTYPE html>  
 <html ng-app="tangled-app">  
   <head>  
......... 
   </head>  
   <body>  
     <div class="container" ng-controller="tangledCtrl">  
       <div class="row-fluid">  
         <h3>Abstract</h3>  
         <p>This a simple customer ajax app with   
           <a href="http://tynamo.org/tapestry-resteasy+guide">Tapestry-resteasy</a> as the backend   
           and <a href="http://angularjs.org/">AngularJS</a> on the front. It also uses   
           <a href="http://twitter.github.io/bootstrap/">Twitter-Bootstrap</a>.</p>  
       </div>  
       <div class="customer-table">  
         <table class="table table-striped table-bordered">  
           <thead>  
             <tr>  
               <th>#</th>  
               <th>Name</th>  
               <th>Address</th>  
               <th>City</th>  
               <th>Country</th>  
               <th>Code</th>  
               <th>Credit Limit</th>  
             </tr>  
           </thead>  
           <tbody>  
             <tr ng-repeat="customer in customers">  
               <td>{{customer.customerNumber}}</td>  
               <td>{{customer.customerName}}</td>  
               <td>{{customer.addressLine1}} {{customer.addressLine2}}</td>  
               <td>{{customer.city}}</td>  
               <td>{{customer.country}}</td>  
               <td>{{customer.postalCode}}</td>  
               <td>{{customer.creditLimit}}</td>  
             </tr>  
           </tbody>  
         </table>  
       </div>  
     </div>  
........
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular.min.js"></script>  
     <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular-resource.js"></script>  
     <script type="text/javascript" src="js/tangled.js"></script>  
   </body>  
 </html>

BTW, if you're using Chrome, you'll get an "access-control-allow-origin" error. To fix this and allow you to continue developing in a local machine then just run Chrome with --disable-web-security. Don't do this though when browsing the internetz.

Designing with the end in mind: tuktuk style

This is part 4 of my Resteasy Tapestry with AngularJS tutorial. This is the design part of the tutorial. Now a days, what good is a web applications if it can't look good. I'm not a UI design expert by any kind of measure, in fact, I pretty much suck at it. So, I'm using somebody else's stuff to get me to look half decent, hence I'm using Javi Jimenez's tuktuk CSS framework.

Tapestry5 Layout sources

In Tapestry, the look of the website is a layout component. It works like pretty much like any other templating system you probably have seen or tried. You have a main template where the smaller page specific templates are "added" into. I have also write about tapestry layouts in a previous tutorial.

The first thing we have to do is add the tuktuk assets like the style sheets and scripts. 

1. Copy the style sheets into the layout folder. You should be adding 3 stylesheets: tuktuk.css, tuktuk.icons.css and tuktuk.theme.css

2. If the folder doesn't exist yet, create a "js" folder in the layout folder and copy the tuktuk.js file into it.

With the assets in place, we need to tell Tapestry5 about it. Open up the layout.java source file in the components folder. And right on top of the class declaration is an @import annotation, this what we change so our Tapestry webapp will be using the tuktuk assets. Change it to:

@Import( stylesheet = {"context:layout/tuktuk.css","context:layout/tuktuk.icons.css",
                       "context:layout/tuktuk.theme.css","context:layout/layout.css"},
        library = {"context:layout/js/tuktuk.js"})

That layout.css stylesheet is your own stylesheet seperate from the tuktuk.css. It's a bad idea to add your own style rules to the tuktuk.css. It's better to use your own.

The last step is to edit the layout.tml. The layout.tml is a very simple HTML template file so it should fairly easy to understand. It's a HTML file for christ sakes!

Easy restful services with tapestry and tynamo-resteasy

This is part 3 of my Resteasy Tapestry with AngularJS tutorial. We will be building the restful api for this tutorial/project. I'll be trying to keep it simple with just CRUD equivalents like GET,  POST, PUT, and DELETE.

First thing first, we will be using Tynamo Resteasy for building the api. We could build our own from scratch but why re-invent the wheel? To add it, you will leverage Maven. Open up your POM file which should be on the root portion of the project and edit it:

<dependency>  
      <groupId>org.tynamo</groupId>  
      <artifactId>tapestry-resteasy</artifactId>  
      <version>0.3.1</version>  
 </dependency>    
 <dependency>  
      <groupId>org.jboss.resteasy</groupId>  
      <artifactId>resteasy-jackson-provider</artifactId>  
      <version>3.0-beta-4</version>  
 </dependency>

We need a JSON marshaller/unmarshaller, hence the resteasy-jackson-provider. We will be working with JSON, no XML. Read the Tynamo-resteasy guide for clarification on this. Now, simply clean and build the project and let Maven do its thing and get all them jars.

The next step is to create the Tapestry service that will respond to AJAX calls. In keeping with Tapestry convention, I'm putting this service inside a package. I called mine: com.demo.tangled.rest. So, it doesn't look so cluttered, I'm just showing the GET method of our restful API inside this service.

package com.demo.tangled.rest;

import com.demo.tangled.dao.contactsDAO;
import com.demo.tangled.entities.Contacts;
import org.apache.tapestry5.ioc.annotations.Inject;
import javax.ws.rs.*;
import javax.ws.rs.core.Response;
import java.util.List;

@Path("/customers")                     // URL for API call     
public class contactsResource{
    
    @Inject                             // Get that DAO service
    private ContactsDAO contactsDAO;
    
    @GET
    @Produces({"application/json"})     // Set output format to JSON
    public List<contacts> getAllContacts(){
        return contactsDAO.getAll();
    }
    .....    
}

The interesting parts of the code are the annotations. The first annotation, @Path, is the URL for API which is appended to rest sub-domain path. So, the address of this resource is http://localhost:8080/tangled/rest/customers if this was running on a local development machine. The other request methods like POST, PUT and DELETE are written in the same manner as the getAllContacts method. Notice the @GET annotation.

I have already wrote about how to make DAO services in my previous Tapestry5 tutorial.

Creating the project in Netbeans with Maven

Modern software development is partly about the tools you use. Just don't insist yours is better with other programmers unless you want to start a religious war.

I use Maven. Maven is a software project management and comprehension tool. It's easy to install and use and Netbeans, my preferred IDE, can work with it by default unlike the other leading IDE which needs a plugin.  

Once you've installed Maven, you'll need to configure Netbeans to use the installed one unless you want to use the bundled one. You can do that via the menu Tools -> Options -> Java(tab) -> Maven. It should auto-detect the Maven home if you installed Maven correctly. After this, you're pretty much set.

Project from Archetype

Now all you need to do is create our Tapestry5.

Create a new project and choose Maven and then Project from Archetype.

We will be using the quickstart Tapestry5 project to get us rolling fairly quickly. The current version should 5.3.7.

On the "next" window, set the values to the following:

• Group ID: org.apache.tapestry
• Version: 5.3.7
• Artifact ID: quickstart
• Repository: http://tapestry.apache.org

You should be able to figure out the next page. After you clicked on that Finish button, you should see the your freshly created Tapestry5 project. 

Before you can run a Tapestry5 project, you need to satisfy a sample requirement which is a create a custom  Maven goal. You'll need this if you want to use the Live Reloading feature. I already wrote a how-to on this in an old blog entry. Just do steps 1, 2 and 3. You don't need to do the rest.

The Tapestry5 running

When you're done, you should be able to run the project and be able to open the web application in your favorite browser. See left. 

If you're wondering, I called my project tangled.

Next week, we'll be working on your database.

Resteasy Tapestry with AngularJS tutorial

I have been on a binge with AngularJS and so far I haven't gone to the hospital. And there's Tapestry5. I have been in-love with it for the longest time.

I think its time for a tutorial.

I'm basically gonna build a simple Tapestry-based restful API and use it with AngularJS. It's not that hard as it sounds. We'll be using Netbeans for this.

Here's what I have planned:

• Creating the project in Netbeans with Maven
• Our Database: Dropping MySQL for MariaDB
• Easy restful services with tapestry and tynamo-resteasy
• Designing with the end in mind: tuktuk style
• DAT Angular

Using JQuery to read an external XML file

A student of mine asked me this question. He wanted to read an external XML file, parse it and load the data into a HTML Form control. In his case, he wanted to populate a select component (combo box). And he didn't want to use any PHP, Java or whatever. So that leaves me with JavaScript and HTML. This intrigued me for a bit. I haven't tried anything like this before.

So after a bit of research I stumbled into jQuery.ajax. I am familiar with jQuery - been using it for a bit so this should be quick. So, we prep the HTML file for our display:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>Parsing Data from a File</title>

        <link rel="stylesheet" type="text/css" href="css/demo.css" />
        <script type="text/javascript" src="js/jquery-1.7.1.min.js"></script>
        <script type="text/javascript" src="js/demo.js"></script>

    </head>
    <body>
        <h2>Parsing Data from a File</h2>
        <p class="compress">Data will be from an external file. It will formatted as an XML file
            (this could be easily be a html file). It will be be parsed using JQuery library.
            We could do this with raw JavaScript but why would you want to do that when
            there is a simpler solution?</p>

        <p>To learn in detail how this thing works <a href="http://api.jquery.com/jQuery.ajax#options">read this.</a></p>

        <div id="form-div">
        Our Combo box:
            <form id="form1" class="cmbox">
                <select class="combo1">
                </select>
            </form>
        </div>       
    </body>
</html> 

And here is the demo.js file that comes with that file. If you run both now you'll get an error. This is because we have to create a file called data.xml. You should also notice that in the demo.js file (refer to the comments) loads the data.xml if it successfully loads the file it should call a function called "parse" and should it fail it calls the "loadfail" function.

$(document).ready(function(){       // load jQuery 1.5
 function loadfail(){
  alert("Error: Failed to read file!");
 }
 
 function parse(document){
  $(document).find("combo").each(function(){
     var optionLabel = $(this).find('text').text();
     var optionValue = $(this).find('value').text();
     $('.combo1').append(
    '' + optionLabel + ''
     );
  });
 }
 
 $.ajax({
  url: 'js/data.xml',    // name of file with our data
  dataType: 'xml',    // type of file we will be reading
  success: parse,     // name of function to call when done reading file
  error: loadfail     // name of function to call when failed to read
 });
});

Here is the data.xml file.

<formdata>
    <combo>
        <value>1</value>
        <text>Option 1</text>
    </combo>
    <combo>
        <value>2</value>
        <text>Option 2</text>
    </combo>
    <combo>
        <value>3</value>
        <text>Option 3</text>
    </combo>
    <combo>
        <value>4</value>
        <text>Option 4</text>
    </combo>
    <combo>
        <value>5</value>
        <text>Option 5</text>
    </combo>
</formdata>

Do note that this will fail with Chrome because of its security model. If you look at the console it will not allow you to load local files because of Origin null is not allowed by Access-Control-Allow-Origin. Whatever that is.