File	Date	Author	Commit
endpoints	2017-08-15	Craig Cocca	[6fdbee] Initial release
LICENSE	2017-08-15	Craig Cocca	[6fdbee] Initial release
README	2017-08-16	Craig Cocca	[fd63ec] Added README with installation instructions and...
index.php	2017-08-15	Craig Cocca	[6fdbee] Initial release
switchtrackresponse.class.php	2017-08-15	Craig Cocca	[6fdbee] Initial release

Read Me

Switchtrack
Framework for RESTful API development in PHP

Copyright 2017 Craig D. Cocca (craig@craigcocca.com)
Released under the MIT License (see LICENSE for details)

INTRODUCTION
------------

Switchtrack provides a framework for developing object oriented, RESTful APIs in PHP. It leverages a router that provides a clean interface between your client-side Javascript framework and database resources in your server environment. 

The reason Switchtrack was created was to provide developers with a straightforard way to implement API endpoints using the object oriented PHP  know-how that you already have.

INSTALLATION
------------
Installing Switchtrack is extremely simple:

1. Create a folder in your web hosting environment that will be the root for all of your API endpoints. A good starting point would be a folder called /api at the root of your site.

2. Unzip or untar Switchtrack into the folder that you created in step 1.  This should result in index.php, switchtrackresponse.class.php, and a folder called endpoints being places into the folder.

3. Configure your web server to correctly route all requests to Switchtrack (see CONFIGURING YOUR WEB SERVER below)

4. Test your installation by calling the example API endpoint included with Switchtrack:  http://yourwebdomain/api/userexample/10/getdisplayname (note: change "api" to the name of the folder you created in Step 1).  If everything is working, a JSON response containing the name of a famous, stranded astronaut should appear.


CONFIGURING YOUR WEB SERVER
---------------------------

Switchtrack relies on server directives on both Apache and nginx servers to funnel requests beneath your API root (/api) to the Switchtrack router for processing.  The following desribes how to configure either server, depending on which you have.

For Apache:

1. Create a file in your /api folder called .htaccess if you don't already have one.

2. Add the following lines to your .htaccess file
	RewriteEngine On
	RewriteBase /api
	RewriteRule ^.+$ index.php [L]

For nginx: 

1. Locate your site configuration file in /etc/nginx/sites-available

2. Add the following line to your server {} block:
	rewrite ^/api/(.*)$ /api/index.php;


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 { 

	}

3. 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

3. 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


4. 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
	}