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. Collection's customization
         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. You can choose the response format by specifying the header Accept. There are two available Content-Type.

format	Content-Type
XML	application/xml
JSON	application/json

If header Accept is not provided, the default format is JSON.

Unique

Unique URI permit to retrieve one resource.

// request
GET https://www.mydomain.com/api/comhon/mymodel/1
Accept: application/xml

// response
200 OK
Content-Type: application/xml

<mymodel id="1" property="value"/>
    <node>value</node>
</mymodel>

Collection

Collection URI permit to retrieve several resource.

// request
GET https://www.mydomain.com/api/comhon/mymodel
Accept: application/json

// response
200 OK
Content-Type: application/json

[
    {
        id: "1",
        value: "my_value_1"
    },
    {
        id="2",
        value: "my_value_2"
    }
]

Collection's customization

Using query parameters

• You can filter returned resources by specifying properties name and filter values.
  For example if you want men called john doe, request and response may look like :

// request
GET https://www.mydomain.com/api/comhon/man?firstName=john&lastName=doe
Accept: application/json

// response
200 OK
Content-Type: application/json

[
    {
        id: 3,
        firstName: "john",
        lastName: "doe",
        mother: 1,
        father: 2
    }
]

• You can filter a property that may have several values (like a IN operator). To do so, you have to suffix property name by []. For example if you want women called emily or jane, request and response may look like :

// request
GET https://www.mydomain.com/api/comhon/woman?firstName[]=emily&firstName[]=jane
Accept: application/json

// response
200 OK
Content-Type: application/json

[
    {
        id: 10,
        firstName: "emily",
        lastName: "doe"
    },
    {
        id: 11,
        firstName: "jane",
        lastName: "doe"
    },
]

• By default, filter is a conjonction, that mean if you have conditions on several properties, conditions are linked by AND operator. But you can set a disjunction (OR) by adding __clause__ query parameter. For example if you want women that have firstName emily or lastName smith, request and response may look like :

// request
GET https://www.mydomain.com/api/comhon/woman?firstName=emily&lastName=smith&__clause__=disjunction
Accept: application/json

// response
200 OK
Content-Type: application/json

[
    {
        id: 10,
        firstName: "emily",
        lastName: "doe"
    },
    {
        id: 20,
        firstName: "jane",
        lastName: "smith"
    },
]

• You can order returned resources with qurey parameter __order__. Order may be ascending or descending and may be set on several properties. Order value must be a JSON. For example if you want men ordered by firstName ascending and lastName descending, request and response may look like :

// request
GET https://www.mydomain.com/api/comhon/man?__order__=[{"property":"firstName", "type":"ASC"},{"property":"lastName", "type":"DESC"}]
Accept: application/json

// response
200 OK
Content-Type: application/json

[
    {
        id: 10,
        firstName: "emily",
        lastName: "smith"
    },
    {
        id: 20,
        firstName: "emily",
        lastName: "doe"
    },
]

Using body

HEAD

POST

PUT

DELETE