2. Creating an API

Before we get going, we should agree on some definitions related to RESTful systems.

Resource is any information that you want to share publicly. It could be a document, an image, or some rows from your database. In Fabstract, Resources are PHP classes, like UserResource.php. Resources have routes, like '/user'. When parsing a URL, resource 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 Resource

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. UserResource.
3. Extend it from \Fabstract\Component\Http\ResourceBase
4. Implement the method configureEndpointBag($endpoint_bag).

Example:

UserResource.php

<?php

namespace Fabstract\Component\SimpleRestApplication\Module\Resource;

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

class UserResource extends ResourceBase
{

    /**
     * @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:

UserResource.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:

UserResource.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 Resource to a URL

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

class ResourceProvider extends ResourceProviderBase
{

    /**
     * @param ResourceBag $resource_bag
     * @return void
     */
    public function configureResourceBag($resource_bag)
    {
        $resource_bag->create('/user', UserResource::class);
    }
}

You're done. You wrote your first API! Now /user URL will be redirected to UserResource.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 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"}