Creating your first Switchtrack handler class

CREATING YOUR FIRST HANDLER CLASS
In Switchtrack, API endpoints are defined through the creation of PHP classes. For example, one may want to make available information about their web site users through a web service that can be called from a client side framework like AngularJS. We have included an example class called UserExample (located in the endpoints subfolder) that implements such a service.

Here, we will walk through the creation of UserExample as a springboard for the development of your first SwitchTrack handler class.

First off, let's be clear about what we want to accomplish. Our goal is to build a service called UserExample that we can call from the web like this:

http://www.mywebsite.com/api/userexample

But, we don't just want information about any user. We want to be able to tell UserExample which user ID we're after. Let's modify our URL to specify a user with an ID of 20:

http://www.mywebsite.com/api/userexample/20

Now we're getting somewhere. We have specified that we want to call a service called UserExample and get information on user number 20. But it would be MORE interesting if we could tell Switchtrack what information we're after about user 20. Let's call a method endpoint to specify exacttly what we want to know about user 20:

http://www.mywebsite.com/api/userexample/20/getdisplayname

Now that we have a fully formed request, let's see what kind of response we get back:

{"displayName":"Jason Bourne"}

As you can see, we get a JSON response back that tells us that the display name of user 20 is Jason Bourne.

By now I'm sure you're asking, "How does Switchtrack make it both EASY and AWESOME to develop a service like this?" Here, we are going to show you how:

1. First, you'd create a file called userexample.class.php in the "endpoints" folder (you'll find that this example file already exists in the standard distribution of Switchtrack).

2. Next, you're going to create a basic class in userexample.class.php

    class UserExample { 

    }

1. Our UserExample service needs to be able to take one argument - the ID number of the user, so we add a constructor to take care of that:

    class UserExample { 
        function __construct($userID) { 

        }
    }

It's important to stop and note at this point that Switchtrack automatically parsed from the URL the name of the handler class that we wanted to use (UserExample) and figured out that the class takes one argument, which is the value stored in the next branch of the URI (20):

http://www.yourdomain.com/api/userexample/20

1. Now that we've created the handler class and set it up to take one argument, we need to make our handler do something useful. Let's add the getDisplayName() method, and then we'll show you how to tie it all together:

class UserExampe { 
        private $user;
        function __construct($userID) { 
            $this->user = getUserInfo($userID);
        }

        function getDisplayName() { 
            // Do stuff here
            return array("displayname"  =>  "Jason Bourne");
        }

        private function getUserInfo($userID) { 
            // Pull user info from backend DB and return
        }
    }

With this fully fleshed out handler class, we can call the complete endpoint to get the requested information on user 20:

http://www.yourdomain.com/api/userexample/20/getdisplayname

1. Taking things one step further, let's say we want to have the endpoint method getDisplayName() accept an argument, like the formatting argument below:

   http://www.yourdomain.com/api/userexample/20/getdisplayname/allcaps

Making this happen is easy. Just modify the getDisplayName() method to accept one argument, which Switchtrack will automatically parse from the URL and pass into getDisplayName()::

function getDisplayName($format) { 
    // Get the display name of the user and format it
    // per the requested style in $format
}