REST API

Table of Contents

1. Preamble
2. Server
   1. Apache server setup
   2. Entry point
      1. Base path
      2. Requestable models
3. Client
   1. OPTIONS
   2. GET
      1. Using query parameters
      2. Using body
   3. HEAD
   4. POST
   5. PUT
   6. DELETE

Preamble

Comhon! framework permit to build REST API without any line of codes. Actually you just have to define manifest, serialization, options and Comhon! do the rest!

Dockers images are available on Docker Hub in repository comhon/comhon. Each following example may be tested with the image 0.1-sample.
To launch a container locally you just have to execute following command.

> docker run -p 80:8000 comhon/comhon:0.1-sample

Server

We will use and configure an apache server as example.

Apache server setup

We route all HTTP requests to an unique entry point index.php by defining .htaccess file. These two files must be in same directory.

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond   %{REQUEST_FILENAME} !-d
    RewriteCond   %{REQUEST_FILENAME} !-f
    RewriteRule   ^((?s).*)$ index.php
</IfModule>

Note that using .htaccess files requires your apache installation to have the AllowOverride All option set.

Entry point

The entry point PHP file must contain at list comhon dependency, the path to configuration file and a call to HTTP request handler.

<?php

use Comhon\Api\RequestHandler;
use Comhon\Object\Config\Config;

// dependencies
require_once __DIR__ . DIRECTORY_SEPARATOR . 'vendor' . DIRECTORY_SEPARATOR . 'autoload.php';

// set the path to configuration file
$config_af = __DIR__ . DIRECTORY_SEPARATOR . 'config' . DIRECTORY_SEPARATOR . 'config.json';
Config::setLoadPath($config_af);

// Comhon framework handle common requests
$response = RequestHandler::handle('/api/comhon');

// send response to client
$response->send();

Base path

The base path is the first parameter pass to RequestHandler::handle() function. This parameter is required. It permit to know which route handler must handle.

For example if we set base path as '/api/comhon' :

• Following uri will be handled

GET https://www.mydomain.com/api/comhon/mymodel/myid
PUT https://www.mydomain.com/api/comhon/mymodel/myid

• Following uri will not be handled

PUT https://www.mydomain.com/comhon/mymodel/myid
GET https://www.mydomain.com/api/mymodel/myid
PUT https://www.mydomain.com/api/comhonmymodel/myid

If a uri is not handled, the returned response contain status code 404 and message not handled route

Requestable models

The Requestable models is the second parameter pass to RequestHandler::handle() function. This parameter is optional. It permit to define a list of models that client may request. Requestable models must be an associative array, each key is the route model name and the value is a fully qualified model name.

Example :

[
    "person": "Test\Person",
    "woman": "Test\Person\Woman",
    "man": "Test\Person\Man",
    "house": "Test\House",
]

• If Requestable models is provided, only specified models are requestables and the uri must contain route model name

GET https://www.mydomain.com/comhon/person/myid

• If Requestable models is not provided, all models are requestable and the uri must contain fully qualified model name (warning \ must be encoded)

GET https://www.mydomain.com/comhon/Test%5cPerson/myid

Client

OPTIONS

GET

Using query parameters

Using body

HEAD

POST

PUT

DELETE