PHP Classes

Very Simple API: Implement REST APIs using service classes

Recommend this page to a friend!
  Info   View files Example   View files View files (17)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 198 All time: 8,486 This week: 125Up
Version License PHP version Categories
vsapi 1BSD License5PHP 5, Web services
Description 

Author

This package can implement APIs using service classes.

It can load service classes that can handle GET, POST, DELETE, PATCH requests if they implement the respective handler functions.

The classes are loaded from a previously configured services directory with the class script file path being determined from the API call version number and service name passed in the request URL.

Picture of Marcel Kohls
  Performance   Level  
Name: Marcel Kohls <contact>
Classes: 2 packages by
Country: Brazil Brazil
Age: 43
All time rank: 3187235 in Brazil Brazil
Week rank: 312 Up26 in Brazil Brazil Up

Recommendations

rest api class php 5.6
rest api php

Suitable out of the box REST API
REST API to replace service without a backend

Example

<?php
   
/**
    * This file is part of the VSAPI (Very Simple API).
    *
    * VSAPI is a free project: you can redistribute it and/or modify it under the terms of the Apache License as published by the Apache.org.
    * The VSAPI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Apache License for more details.
    * You should have received a copy of the Apache License along with VSAPI. If not, see http://www.apache.org/licenses/.
    *
    * @author Marcel Kohls (cerealmx@gmail.com)
    * @license http://www.apache.org/licenses/ or/and https://choosealicense.com/licenses/apache-2.0/
    * @link https://github.com/marcelkohl
    */

   
header('Access-Control-Allow-Origin: *');

    require_once(
'includes/global-settings.php');
    require_once(
SRC_INCLUDES.'/autoload.php');

    require_once(
SRC_INCLUDES.'/header-status.php');
    require_once(
SRC_INCLUDES.'/exception-thrower.php');
    require_once(
SRC_INCLUDES.'/sanitize.php');
    require_once(
SRC_INCLUDES.'/error-log.php');

   
ExceptionThrower::Start();

   
$vsapiversion = (isset($_REQUEST['vsapiversion']) ? $_REQUEST['vsapiversion'] : '');
   
$vsapiservice = (isset($_REQUEST['vsapiservice']) ? $_REQUEST['vsapiservice'] : '');
   
$vsapiuid = (isset($_REQUEST['vsapiuid']) ? $_REQUEST['vsapiuid'] : '');

    try{
        if (
file_exists(SRC_SERVICES.'/'.$vsapiversion.'/'.$vsapiservice.'.php')) {
           
$vsapiservicename = 'services\\'.$vsapiversion.'\\'.$vsapiservice;
        } else {
           
$vsapiservicename = 'services\\Undefined';
        }

       
$serviceToRun = new $vsapiservicename();
       
$serviceToRun->execute();
    } catch(
Exception $e) {
       
saveErrorLog($vsapiservice, $e);
    }

   
ExceptionThrower::Stop();


Details

Very Simple API Pack

The very simple API pack is an effort to make a pack with the very basic stuff to those developers who needs to make an API but doen't want to start from the very beggining.

The vsapi pack now in on the level 2 maturity level (and I hope to soon be on Level 3), it covers the following basic resources of an API: * REST or XML-RPC Calls (Automatic detection or Restricted by the developer) * Run specific methods according to the method call (POST, GET, PUT, PATCH, DELETE, OPTIONS or Restricted by the developer) * Answering on standards REST and XML-RPC * Exception Handler * Sanitization to avoid injection * Transparent Log Error (write internal errors to file) * Versioning services control

Setting up

The Very Simple API Pack is ready to go, just unpack the files, set-up the global settings with your server path, API name and version and it will be working.

  • Unpack the files on a folder on your server;
  • Edit the ```include/global-settings.php``` file and edit your path, api name, version, and default page for error reference;
  • Edit the ```.htaccess``` to fit your server path

If everything goes right, the sample service (Ping) should work:

http://your-server-name/vsapi/v1/Ping

More samples can be found at the examples folder.

How does it works

URL

The vsapi API URL is interpreted by the htaccess file as:

http://[server/path/to/api]/[version]/[service-to-call]/[optional-unique-id]

Folders

The vsapi pack is structured as the following: * /classes * The core classes that makes the API work; * /includes * Configuration files, additional resources and libs to deal with headers, exceptions, sanitization and errors; * /services * where the files of your services should be added. the structure is based on versioning and should be like: /services/v1, /services/v2, /services/v... * /tempfiles * folder to use for temporary files. Also used by the exception logger; * index.php * manages the requests, check the existence of the services and redirects to the right ways;

Reference

Constants

The constants declarated on the API are: * `API_ROOT`: Root path to the API * `API_LOCALPATH`: Folder path to the API * `API_FULLPATH`: Complete path to the API * `API_NAME`: Name description for the API * `API_DEFAULT_ERROR_REFERENCE`: Default reference page mentioned on answers when some error occurs * `SRC_TEMPFILES`: tempfiles folder * `SRC_CLASSES`: classes folder * `SRC_INCLUDES`: includes folder * `SRC_SERVICES`: services folder * `VERSION_MAJOR`: version major number * `VERSION_MIDDLE`: version middle number * `VERSION_MINOR`: version minor number

  • Allowed methods: ```AMT_GET, AMT_POST, AMT_PUT, AMT_PATCH, AMT_DELETE, AMT_OPTIONS```
  • Answer types: ```AST_AUTO, AST_JSON, AST_XML```

Classes

Public Methods of `AbstractService` * `initialize(arrayOfArguments)`: Initializes the service enviroment. Should be called with an array of arguments that specifies the allowed methods and the answer types;

    $this->initialize([
    	'allowedMethods'=>[AMT_GET, AMT_POST, AMT_OPTIONS],
        'answerType'=>AST_AUTO
        ]);

* `execute()`: Called automatically when the API is called. Must include the initialization settings and the of the service and the `initialize` method. * `onGet()`: Called when the method used is a GET type * `onPost()`: Called when the method used is a POST type * `onPut()`: Called when the method used is a PUT type * `onPatch()`: Called when the method used is a PATCH type * `onDelete()`: Called when the method used is a DELETE type * `onOptions()`: Called when the method used is a OPTIONS type. This method dont need to be overwritten because it alread answers as it should be. * `getFields()`: returns an array with the fields that came on the request; * `getValue(fieldName)`: returns the value of a specific field that came on the request;

    $this->getValue('userId');

* `answer(arrayOfValues)`: Returns a formated answer according to the answerType defined on the initialization.

    $this->answer([
				'message' => 'Here are the fields that the API received',
				'fields' => $this->getFields(),
                'nameOfTheField' => 'the Value here'
			]);

* `answerAsFailedValidation(optionalArrayOfValues)`: Returns a formated error/fail message answer according to the answerType defined on the initialization. The array of values to return is optional and if is not provided, a generic message will be returned.

$this->answerAsFailedValidation([
	'validation_messages' => [
                              'uniqueId'=>'Unique ID is a required field',
                              'email'=>'your email is not valid',
                              'mySpecificField'=>'Message for the field'
                             ]]);

How to use

Calling a REST service through AJAX

function postItem() {
    $.ajax({
        type : 'POST',
        url : "http://api-server-name/v1/Ping",
        data : JSON.stringify({
                    "message": "sample message here",
                    "user": "the-best-user-ever",
                    "list": ["first", "second", "third"]
                }),
        contentType: "application/json",
        success : function(data){
            // use your code here to process data content returned
        }
    });
}

Calling a XML-RPC service through PHP

$method = "POST";
    $request = xmlrpc_encode_request("methodName", array("methodParam"=>"param1", "otherMethodParam"=>"param2 with spaces"));
    $context = stream_context_create(array('http' => array(
        'method' => $method,
        'header' => "Content-Type: text/xml",
        'content' => $request
    )));

    $file = file_get_contents("http://localhost/vsapi/api/v1/Ping", false, $context);
    $response = xmlrpc_decode($file);

    if (xmlrpc_is_fault($response)) {
        trigger_error("xmlrpc: $responsefaultString");
    } else {
        print_r($response);
    }

To-do

Here are some resources that still need to be implemented on the pack:

  • Unique ID transaction: Automatically control/manage and generate the unique id for each transaction, as defined on the REST standards;
  • Fields permission: The hability to define which fields are required, optional, or free on the request;
  • Filtering and Validation: To automatically filter or validate the fields of request (less than, lower than, not blank, remove spaces, etc);
  • Returning types: as a register or collection;
  • htaccess limits: Adjust the htaccess to avoid setting up it on every new project/domain;
  • Error codes returned by the API: Need to review if all the codes fits the specification and cover other error codes;
  • Documentation: Define ways to automatically generate documentation;
  • Authenticantion: Need to implement HTTP Basic authentication (htpasswd), Digest, or OAuth2;

License

vsapi API Pack is a free project: you can redistribute it and/or modify it under the terms of the Apache License as published by the Apache.org. The vsapi is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Apache License for more details.


  Files folder image Files  
File Role Description
Files folder imageclasses (2 files)
Files folder imageexamples (2 files)
Files folder imageincludes (7 files)
Files folder imageservices (1 file, 1 directory)
Accessible without login Plain text file .htaccess Data Auxiliary data
Accessible without login Plain text file index.php Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  classes  
File Role Description
  Plain text file AbstractService.php Class Class source
  Plain text file ServiceAnswer.php Class Class source

  Files folder image Files  /  examples  
File Role Description
  Accessible without login Plain text file test-ajax.html Data Auxiliary data
  Accessible without login Plain text file test-xml-rpc.php Aux. Auxiliary script

  Files folder image Files  /  includes  
File Role Description
  Accessible without login Plain text file autoload.php Aux. Auxiliary script
  Accessible without login Plain text file error-log.php Example Example script
  Plain text file exception-thrower.php Class Class source
  Accessible without login Plain text file global-settings.php Conf. Configuration script
  Accessible without login Plain text file header-status.php Aux. Auxiliary script
  Accessible without login Plain text file header.php Aux. Auxiliary script
  Accessible without login Plain text file sanitize.php Aux. Auxiliary script

  Files folder image Files  /  services  
File Role Description
Files folder imagev1 (1 file)
  Plain text file Undefined.php Class Class source

  Files folder image Files  /  services  /  v1  
File Role Description
  Plain text file Ping.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:198
This week:0
All time:8,486
This week:125Up