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

Comhon! permit to retrieve, create, update and delete resources very easly. We will eplain how client must use API for each actions.

There are two kind of URI that comhon API is able to handle : Unique and Collection.

Unique

Unique URI look like :
domain / base path / resource model name / resource identifier
It might be use to retrieve, create, update, or delete a unique resource identified by its identifier.

Collection

Collection URI look like :
domain / base path / resource model name
It might be use to retrieve several resources in same time or to create a unique resource with an auto generated identifier on server side.

OPTIONS

OPTIONS method permit to know allowed methods (in response header Allow). If an options manifest file is defined on server side, options are returned in response body, otherwise the response body is empty.

// request
OPTIONS https://www.mydomain.com/api/comhon/mymodel/myid

// response
200 OK
Allow: OPTIONS, GET, HEAD, PUT, DELETE

// request
OPTIONS https://www.mydomain.com/api/comhon/mymodel

// response
200 OK
Allow: OPTIONS, GET, HEAD, POST

GET

GET method permit to retrieve one or several resources.

Unique

Collection

Using query parameters

Using body

HEAD

POST

PUT

DELETE