2.2. REST API resources

As mentioned in the previous section, the workflow system contains several pre-defined and ready-to-use REST APIs.

Please refer to the Package pre-defined routes section for more information on these REST Apis.

To make it easy to use, we will group this REST APIs by 4 groups:

1. Retrieving the data list
2. Retrieving a data with its identifier (id)
3. Creating / Updating an instance
4. Deleting an existing instance

1. Retrieving the data list

The next routes (see below) are designed with the same logic and return the same data structure:

Routes list

• GET|HEAD api/modules
• GET|HEAD api/actions
• GET|HEAD api/status
• GET|HEAD api/workflows

Routes responses

All this routes return the same object Heloufir\SimpleWorkflow\Core\PartialList, this object contains fields helping you to structure your data into pages. The structure of this object:

Field	Type	Description
$data	Illuminate\Support\Collection	The data retrieved from the query builder
$count	int	The total count of all lines from database
$page	int	The page retrieved from database
$size	int	The size of the page retrieved

The REST APIs resources use the trait Heloufir\SimpleWorkflow\Core\Paginator that you can use to paginate your Eloquent query builder results based on a request object. When using it, you need to send the following parameters into your HTTP requests:

• size: this parameter is required to execute the pagination function, it means the number of line to get from database
• page: this parameter means, which page you need to show from database (this parameter is optional, by default the first page is retrieved)

How to use it

You need first to use the trait into your controller, then execute the paginate(Builder, Request) function, see the example below:

<?php

// ...
use Illuminate\Http\Request;
use Heloufir\SecurityStarter\Core\Paginator;

class YourController extends Controller {

    use Paginator;

    public function index(Request $request) {
        $query = YourModel::query();
        // $query->... Add your conditions
        return response()->json(self::paginate($query, $request), 200);
    }

}

Routes response statuses

The response of all this routes has always the status 200.

2. Retrieving a data with its identifier (id)

Routes list

• GET|HEAD api/modules/{module}
• GET|HEAD api/actions/{action}
• GET|HEAD api/status/{status}
• GET|HEAD api/workflows/{workflow}

Routes responses

The object return by this route are the model to get, so for example for the route api/modules/{module}, the REST api resource will execute a request in the database searching the module object where it's identifier equal the value of the {module} and return the first result into the body of the response.

Routes response statuses

The response status will be 200 if the object is found in the database, and status 404 instead (if the object does not exists in the database).

3. Creating/ Updating an instance

For both the creation and update routes listed below, the business logic is the same, first there is a form validations to check the validity of the data sent in the HTTP request, if all is correct then the instance is saved into the database.

Routes list

• POST api/modules
• POST api/actions
• POST api/status
• POST api/workflows
• -
• PUT|PATCH api/modules/{module}
• PUT|PATCH api/actions/{action}
• PUT|PATCH api/status/{status}
• PUT|PATCH api/workflows/{workflow}

Routes responses

All this routes return the object instance into the body of the HTTP response.

Routes response statuses

The response status will be 200 if the object is successfully saved into the database, and status 403 if the form validation failed, and the body of the HTTP response will be an array of the form validation error messages.

Below is an example of an error while saving an action instance:

[
    "The code field is required.",
    "The designation field is required."
]

4. Deleting an existing instance

Routes list

• DELETE api/modules/{module}
• DELETE api/actions/{action}
• DELETE api/status/{status}
• DELETE api/workflows/{workflow}

Routes responses

All this routes return a boolean into the body of the HTTP response, this boolean equal TRUE if the object is deleted or FALSE instead.

Routes response statuses

The response of all this routes has always the status 200.