====== Feng Office API Developer's Guide ======

===== Description =====

The Feng Office API provides a powerful and simple Web Service interface to interact with your Feng Office installation. It's based on a RESTful and Stateless web service, over JSON Internet Media Type.

For the Feng Office API, we use the Lumen microframework. Check the documentation at
https://lumen.laravel.com/docs/10.x

===== Requirements =====

  - OpenSSL PHP Extension
  - PDO PHP Extension
  - Mbstring PHP Extension
  - Composer

===== Configuration =====

Configure the ''.env'' file.

  - Copy ''application\api\.env.example'' to ''application\api\.env''
  - Edit the file and replace it with your root credentials and your database name:<code>
    DB_DATABASE=homestead
    DB_USERNAME=homestead
    DB_PASSWORD=secret </code>  
  - Save and close the file.

===== Composer =====

In your API installation dir (feng/application/API):

- Run composer install to install all the libraries that depend on the project.
<code>/var/www/html/feng/application/api$ composer install</code>
  
===== For Development =====

To serve the Feng Office API for development mode use:

  - Go to your installation directory (feng) 
  - Go to API directory (feng/application/API)
  - Run php -S localhost:8000 -t public
  - Go to your browser and put the URL: localhost:8000
  - If everything is OK you will see the result: “Lumen (8.3.4) (Laravel Components ^8.0)”

===== Production Endpoint =====

General test:

To test that it is in production in your browser go to your installation directory 
<code>/application/API/public/</code> and you will see “Lumen (8.3.4) (Laravel Components ^8.0)”. 

That indicates that Feng API is working!

===== How to create a new method =====

==== Create the route: ====

You will define all of the routes for your application in the routes/web.php file.

The most basic Lumen routes accept a URI and a Closure:
<code>
$router->get('foo', function () {
  return 'Hello World';
});
$router->post('foo', function () {
  //
});</code>

=== Available Router Methods ===

The router allows you to register routes that respond to any HTTP verb:

<code>
$router->get($uri, $callback);
$router->post($uri, $callback);
$router->put($uri, $callback);
$router->patch($uri, $callback);
$router->delete($uri, $callback);
$router->options($uri, $callback);</code>

==== Create the controller: ====

Instead of defining your request handling logic in a single routes/web.php file,
you may wish to organize this behavior using Controller classes. Controllers can
group related HTTP request-handling logic into a class. Controllers are stored in the
app/Http/Controllers directory.

Basic Controllers example
Here is an example of a basic controller class. All Lumen controllers should extend
the base controller class included with the default Lumen installation:
<?PHP
  namespace App\Http\Controllers;
  use App\User;
  class UserController extends Controller
  {
    /**
    * Retrieve the user for the given ID. 
    *
    * @param int $id
    * @return Response
    */
    public function show($id) {
      return User::findOrFail($id);
    }
  }
  
We can route to the controller action like so:
<code>$router->get('user/{id}', 'UserController@show');</code>
Now, when a request matches the specified route URI, the show method on the
UserController class will be executed. Of course, the route parameters will also
be passed to the method.

===== Parameters =====

Base URI (or Endpoint)
Endpoint URL: <code>FENGOFFICE_URL/application/API/public</code>
If your Feng Office installation is accessible by the following url: http://example.com/feng then your API endpoint is: http://example.com/feng/application/api/public

===== Method =====

This version counts with the following method to be invoked:

  * loginUserByToken
 

To invoke a remote method you need to make a request to the following URL:
http://example.com/feng/application/api/public/METHOD_NAME/&exampleParam=1

===== Authentication =====

Each web service request must include a GET parameter ‘auth’ containing a hash of the user password. This hash is the user token generated automatically when a user is created.