README

This packages provides platform for writing RESTFul APIs in PHP

Introduction

RESTful APIs are modern way of designing an web application , this approach provides the UI Dresigners complete freedom of their design and improvement

RESTFul APIs also give a way to secure the web resources in more elegant way

This package provides a platform for creating such RESTFul APIs in PHP

Features

• Annotated APIs
• can be used with any frameworks

Usage

• copy resources/.htaccess and resources/index.php to the root of the composer package
• enable apache rewrite module
• add AllowOveride All to composer root directory in apache's configuration
• Service Class must implement `PhpPlatform\RESTFul\RESTService`
• annotate service classes and methods with `@Path` to specify the path to which the the perticular class::method provides the service
• configure routes as mentioned in the Configuration section below
• All service methods must return `PhpPlatform\RESTFul\HTTPResponse`

Annotations

@Path

Can be applied on service class or method , this denotes url path to reach that service-method

@GET @POST @PUT @PATCH @HEAD @DELETE

Can be applied only on service method , denotes what http verb this method is capable of serving. A service method can have more than on of these Annotations If a service method has @Path annotation and has no HTTP methods , @GET is applied by default

@Consumes

Cab be applied only on service method, specifies the data type of the request body

deserializers use this annnotation to deserialize the http request body into a php data. refer deserilizers section to configure multiple deserializers

@ReCaptcha

Enables service method to have recaptcha authenticated. Considered when recaptcha.enable configuration is set to true

NOTE : service request should send the recaptcha response as http header Php-Platform-Recaptcha-Response

@CORS.force

Can be applied on service class or method Forces Origin Header to be present in Request This Annotation forces CORS on a service, see CORS section of this document for more information

Configuration

This section explains the configuration for this package which can be configured using config.xml

serializers

Differrent type of data needs to be serialized in differrent formats based on the Accept Header in the request

So differrent serializing implementations can be configured as follows

"serializers":{
        "array":{
            "application/json":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
        },
        "SimpleXMLElement":{
            "application/xml":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
        }
    },

Serializer class must implement `PhpPlatform\RESTFul\Serialization\Serialize` interface

deserializers

The data in the http request must be converted into a php represenation So differrent deserializing implementations can be configured as follows

"deserializers":{
        "application/json":{
            "array":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
        },
        "application/xml":{
            "SimpleXMLElement":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
        }
    },

Deserializer class must implement `PhpPlatform\RESTFul\Serialization\Deserialize` interface

The PHP type to which the data should be converted needs to be specified at an annotation for the service as follows

/**
 * @Consumes array
 * @Path my-service
 */
function myService(){}

routes

routes is the static map of url pattern to service class and methods.

routes can be updated manually or generated based on the annotations by running

$ ./vendor/bin/build-restful

routes is organized as a tree , where each node contains the class and method name of the service available for that url path

web services for these url patterns will be configured as follows

• `GET /user/all :- MyService\User::getAllUsers`
• `POST /user/create :- MyService\User::createUser`
• `GET /user/{id} :- MyService\User::getUser`

"routes" : {
    "children" : {
        "user" : {
            "children" : {
                "all" : {
                    "methods" : {
                        "GET" : {
                            "class" : "MyService\\User",
                            "method" : "getAllUsers"
                        }
                    }
                },
                "create" : {
                    "methods" : {
                        "POST" : {
                            "class" : "MyService\\User",
                            "method" : "createUser"
                        }
                    }
                },
                "*" : {
                    "methods" : {
                        "GET" : {
                            "class" : "MyService\\User",
                            "method" : "getUser"
                        }
                    }
                }
            }
        }
    }
}

`NOTE :`

`The parameters in the path are represented as * in the config , in the above example {id} is represented as *`

`Name of the params does not map to the name of the service method arguments , but they map to the position`

recaptcha

recaptcha configurations enable services to require reCaptcha authentication

"recaptcha":{
    "enable":true,
    "secret":""
}

set enable to true to enable services to have recaptcha

set the value of secret provided from google recaptcha

CORS

CORS configurations enables CORS (Cross Origin Resource Sharing) authentication

"CORS":{
    "AllowOrigins":[
    ],
    "AllowMethods":[
    ],
    "AllowHeaders":[
    ],
    "AllowCredentials":false,
    "MaxAge":1000
}

Details of these can be found in https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS

CORS configurations can be set specific for a Service using Annotations. For example to allow a https://specific.example.com to a specific service

/**
 * ...
 * @CORS.AllowOrigins https://specific.example.com
 */
function mySpecificService(){} 

Access-Control-* Headers

• Access-Control-Allow-Origin This header is set to origin header in the request only if that origin is listed in CORS.AllowOrigins configuration

• Access-Control-Allow-Methods Comma seperated Methods configured in CORS.AllowMethods

• Access-Control-Allow-Headers Comma seperated Headers configured in CORS.AllowHeaders

• Access-Control-Allow-Credentials True/False configured in CORS.AllowCredentials

• Access-Control-Max-Age number of seconds configured in CORS.MaxAge

• Access-Control-Exposed-Headers Comma separated names of headers explicitely set in HTTPResponse object from the service