2. Creating an API

Before we get going, we should agree on some definitions.

Controller is where people can access the resources or information about resources that you want to share publicly. It could be a document, an image, or some rows from your database. You can name them anything, but it is recommended for a Controller to have the same name as its route, like /user should be mapped to UserController. It is also recommended to have noun names for controllers, like SessionController and not LoginController. When parsing a URL, controller is matched right before endpoint.

Endpoint is an address to one or more APIs, i.e. Actions. Endpoints have routes, like '/', '/1' or '/1/settings'. When parsing a URL, endpoint is the end of the URL. It is the last point, the end point. There is nothing coming after it.

Action is composed of an HTTP method and a PHP function. You can add actions to your endpoints like GET, POST etc and point them to a callable/function by using actions.

For a detailed description about REST, you can read this.

1. Create a Controller

1. Pick a name, it should be a noun like user or product. It should NOT be a verb, like register or buy.
2. Create a PHP file, and a class with the same name as file. Ex. UserController.
3. Extend it from \Fabstract\Component\Http\ControllerBase
4. Implement the method configureEndpointBag($endpoint_bag).

Example:

UserController.php

<?php

namespace Fabstract\Component\SimpleRestApplication\Module\Controller;

use Fabstract\Component\Http\Bag\EndpointBag;
use Fabstract\Component\Http\ControllerBase;

class UserController extends ControllerBase
{

    /**
     * @param EndpointBag $endpoint_bag
     * @return void
     */
    public function configureEndpointBag($endpoint_bag)
    {
        // TODO: Implement configureEndpointBag() method.
    }
}

2. Create an Endpoint

1. Pick a routing for URL, like / or /name.
2. Create the endpoint by using create() method.

Like below:

UserController.php

public function configureEndpointBag($endpoint_bag)
{
    $endpoint_bag->create('/');
}

3. Add Actions to the Endpoint

1. Create the function that your endpoint will execute.
2. Map the function with corresponding HTTP method by using corresponding endpoint methods, like addGET().

Like below:

UserController.php

public function configureEndpointBag($endpoint_bag)
{
    $endpoint_bag->create('/')
        ->addGET('get')
        ->addPOST('create');
}

public function get() {
    return 'inside get function';
}

public function post() {
    return 'insude post function';
}

4. Map Controller to a URL

Finally, you should map the controller you created to a URL inside your ControllerProvider.php file, like this:

class ControllerProvider extends ContollerProviderBase
{

    /**
     * @param ControllerBag $controller_bag
     * @return void
     */
    public function configureControllerBag($controller_bag)
    {
        $controller_bag->create('/user', UserController::class);
    }
}

You're done. You wrote your first API! Now /user URL will be redirected to UserController.php file.

If you GET

curl -i -X GET yourdomain.postfix/user

you should see the following:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"success","data":"inside get function"}

or POST

curl -i -X POST yourdomain.postfix/user -H"Content-Type: application/json"

you should see the following:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"success","data":"inside post function"}

If you send an unmapped HTTP method, you will get HTTP 405

curl -i -X HEAD yourdomain.postfix/user

will result below:

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{"error_message":"method_not_allowed","status":"failure"}

If you try to access a controller (i.e. a resource) that's not mapped, you get HTTP 404

curl -i -X HEAD yourdomain.postfix/product

will result below:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error_message":"not_found","status":"failure"}

Next topic: HTTP Status Codes