isoTope Documentation: Service handler API

This is a very simple API to handle Atom services. The most commonly used Atom services are the blog service and the search service. The serviceAPI defines common methods that need to be implemented to be a service within the PHP AtomAPI implementation.

The design criteria was to keep services independant of the framework and the storage, while also allowing one service to be used multiple times with different configurations.

A service is defined on two levels:

• Class definition: The blue print of a service.
• Object definition: One or more implementations or instantiations of a service

---

Class definition

All source files implementing services are named with the pattern service{ServiceClassName}.php. All services extend the BaseClassService class.

Each service handler is defined as:

class {ServiceName}Service extends BaseClassService {

}
				

Functions

The following functions need to be implemented by a new service class:

function init($serviceName)

Initialise the service. This is called immediately after instantiating this service. The initialisation function needs to initialise and store a reference to a storage class. Configuration options are provided by $services[$serviceName] which returns a list of configuration settings.

function doGet()

Handles all GET requests.

function doPost()

Handles all POST requests.

function doPut()

Handles all PUT requests.

function doDelete()

Handles all DELETE requests.

function doOptions()

Handles all OPTIONS requests.

---

Object definition

Each running service is keyed by a service key. This is a short keyword for a particular implementation of service. For example one blogging service can have the service key of blog. It would then be available on the URL at http://www.example.com/atom/blog/ if the atom base URL is http://www.example.com/atom/. Each service is just a "subdirectory" of the atom base.

Running a new service

A new service requires the following information to be configured:

• The title of the service
• Which service class to use
• What storage methods to configure and use

This configuration (plus any other instantiated services configuration) is all done in the atomServices.php file. Essentially each defined running service is an entry in the $services array, using the service key as the key. Looking at the blog service:

$services["blog"] = array(
	"class"		=> "Blog",
	"title"		=> "Blog",
	"store"		=> "File",
	"storeDir"	=> "C:/www/phpAtomApi/store/blog/",
);

This defines the uri {atomBaseURI}/blog/ as a service. The array is then a name value pair configuration options. The title array index specifies the title of the service. This is used in the HTML representation, for example, to construct the appropriate link text in the breadcrumb trail. The class array index defines the service type. In this case the service blueprint is Blog. This says that this service is implemented by the file serviceBlog.php. The store array index configures which class to use as a means of storing and retrieving data for this implementation of the service. In this case the class File is used as the storage class. This then allows the class FileStorage as defined in storeFile.php to be used. The FileStorage class requires the service to specify a directory to store its data, this is done above using the storeDir parameter.

And that's it. Your service should now be available on the url {atomBaseUrl}/blog/.