Sample files for demonstrating WellRESTed.

Clone this project onto a server under a website document root.

Download Composer and use it to install the dependencies (WellRESTed). Run the following commands from the root director of the samples.

$ curl -s https://getcomposer.org/installer | php
$ php composer.phar install

For the mini API in the api directory, you may need to modify some paths to fit your installation. The ApiSampleRouter class has a class constant you can modify to fit your installation path.

Also, set the permissions to allow write access for the file /api/lib/ApiSample/data/articles.json if you would like to use the POST, PUT, and DELETE methods to modify the data.

The scripts directory contains several stand-alone examples:

Demonstrates how to create and output an HTTP response, complete with status code, headers, and message body.

Shows how to create a new request and communicate with another server. Specifically, it makes a simple GET request to Google.com and displays the response.

WellRESTed uses PHP's cURL to make HTTP requests, so ensure that you have this installed if you wish to use this feature.

Here we read the request sent to the server and create a response based on the request. The script simply echoes information about the request. The response body contains JSON describing the method, body, and headers used in the original request.

The api directory contains a mini API project that demonstrates the main features of WellRESTed. The following sections will show you how to use the API, and then how the API works under the hood.

For this sample project, the only resources are "articles", which are kind of like little mini blog posts or news feed items. Each article contains the following fields:

• articleId: Numeric unique identifier for the article
• slug: A human-readable, URI-friendly, unique identifier for the article
• title: Text title describing the article
• excerpt: A short portion of the article's content

In JSON, an article resource looks like this:

{
    "articleId": 1,
    "slug": "good-movie",
    "title": "Reports Of Movie Being Good Reach Area Man",
    "excerpt": "Local resident Daniel Paxson has reportedly heard dozens of accounts from numerous friendly sources in the past two weeks confirming that the new James Bond film is pretty good. According to persons with knowledge of the situation, an unnamed friend of Paxson’s coworker Wendy Mathers watched the movie on opening weekend and found it to be “decent enough.”"
}

The API exposes both collections of articles and each article individually.

/articles/

Represents the collection of articles.

• GET Display the full list of articles.
• POST Add a new article. Provide the new article in JSON format as the request body.
• PUT Not allowed
• DELETE Not allowed

/articles/{id} and /articles/{slug}

Represents one specific article identified by the numeric ID {id} or by the alpha-numeric slug {slug}.

• GET Display one specific article.
• POST Not allowed
• PUT Replace the article with the new article. Provide the new article in JSON format as the request body.
• DELETE Remove the article.

Here is a brief summary of the files with descriptions of their roles:

The .htaccess file uses mod_rewrite to direct all incoming requests to non-regular files to the main index.php file.

index.php requires the Composer autoload file, instantiates a Router, uses the Router to find the appropriate Handler class to build the response, and finally outputs the response.

The Router builds a list of rules (called Routes) that determine which Handler class it should defer to based on the request's URI. For example, examine this line from the constructor:

$this->addTemplate('/articles/', 'ArticleCollectionHandler');

This line adds a new Route to the router instructing the Router to look for any request with the URI /articles/. When it receive a request to this URI, it should instantiate an ArticleCollectionHandler instance to deal with the request and issue a response.

The URIs for the routes can also include variables identified by regular expressions. Take a look at the next line in the ApiSampleRouter's constructor:

$this->addTemplate('/articles/{id}', 'ArticleItemHandler', array('id' => Route::RE_NUM));

Here, we're using a URI template to indicate that a variable must follow /articles/. The second parameter says that any requests matching this should be handled by an ArticleItemHandler instance. The third parameter describes the variables contained in the URI template. This parameter is an associative arrays with the keys as variable names from the template and the values as regular expressions that the variables must match. Route::RE_NUM is a predefined constant for digits only, but you can create your own, or use other predefined constants.

For more information on URI templates, see RFC 6570.

This Handler is used whenever the Router receives a request for the URI /articles/. I've called it a "collection" handler because the resources it deals with are lists of articles rather than single articles. This handler allows you to view a list of articles (GET) or add a new article to the list (POST).

The router invokes this Handler whenever it receives a request relating to a single article (hence "item" handler). For example, when you view a specific article (GET), update an existing article (PUT), or delete an article (DELETE).

The ArticleController class takes care of reading from and writing to the data file used to store the articles. This is a really simple example that just writes to a flat JSON file. Your controllers could communicate with databases, caches, etc.

Just a flat file storing some data in JSON format. You'll need to enable write access for this file to try out the POST, PUT, and DELETE methods of the API.

Copyright © 2013 by PJ Dietz Licensed under the MIT license