Requirements

Version 2.x requires October CMS 4 and RainLab.Builder. RainLab.User 3.x is optional and only needed for authentication.

Installation

php artisan plugin:install AhmadFatoni.ApiGenerator

or with composer:

composer require ahmadfatoni/apigenerator-plugin
php artisan october:migrate

If composer runs out of memory, prefix the command with COMPOSER_MEMORY_LIMIT=-1.

Usage

Open API Generator in the backend menu and click Create. You need the Manage the API Generator permission.

Saving the form makes the endpoints available immediately. The edit page of each API lists all of its URLs.

The API definitions are cached and the cache is cleared whenever an API is saved or deleted. If you change the ahmadfatoni_apigenerator_data table directly, for example after a database import, run php artisan cache:clear.

Custom Condition

Use fillable for the columns of the model, and relation for the relations to eager load and their columns. Both are comma separated lists.

{
    "fillable": "id,title,slug,author_id",
    "relation": [
        {
            "name": "author",
            "fillable": "id,title"
        },
        {
            "name": "categories",
            "fillable": "id,title"
        }
    ]
}

For belongsTo relations, include the foreign key (for example author_id) in fillable, otherwise the relation comes back empty. Leave the field empty to return all columns without relations.

Endpoints

For a Base Endpoint of api/v1/posts:

Send the body as JSON (Content-Type: application/json) or x-www-form-urlencoded. PHP does not read multipart/form-data on PUT requests.

Response format

Every response has the same shape:

{
    "status_code": 200,
    "message": "success",
    "data": []
}

Example

curl -X POST "https://example.com/api/v1/posts" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"title":"Hello","slug":"hello","content_group":"regular_post"}'

For Tailor entries that use groups, send content_group with the group handle from the blueprint.

Authentication

Requires RainLab.User. Turn on Require Authentication for an API, and every one of its endpoints then needs a bearer token. APIs with the switch off stay public.

The plugin adds these endpoints while RainLab.User is installed:

The login field follows the RainLab.User Login attribute setting, so use username instead of email if you changed it. Logins go through RainLab.User, so its throttling and events still apply. Accounts with two factor authentication enabled cannot sign in through the API.

Sign in:

curl -X POST "https://example.com/api/v1/auth/login" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"email":"user@example.com","password":"secret"}'

{
    "status_code": 200,
    "message": "success",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "user": {
            "id": 1,
            "first_name": "John",
            "last_name": "Smith",
            "email": "user@example.com"
        }
    }
}

Then send the token with every request to a protected API:

curl "https://example.com/api/v1/posts" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer TOKEN"

Tokens expire after 60 minutes. You can change the lifetime and signing key through the rainlab.user::bearer_token config.

Contributing

Source code, tests and issues are on GitHub. Pull requests are welcome.

Upgrading to 2.x

Version 2.x supports October CMS 4 only. If your site runs October CMS 1, 2 or 3, keep using version 1.x.

Before you upgrade

• Upgrade your site to October CMS 4 first.
• Back up your database, including the ahmadfatoni_apigenerator_data table.
• Write down your API endpoints, so you can check them after the upgrade.

Steps

1. Update the plugin and run the migrations:

   php artisan plugin:install AhmadFatoni.ApiGenerator
   php artisan october:migrate
   php artisan cache:clear

2. Open API Generator in the backend and check each API.

3. For APIs built on a Tailor blueprint, select the model again and save. Tailor models are now stored as tailor:Handle, for example tailor:Blog\Post.

4. Call a few endpoints to confirm they respond as before.

What changed

• No generated files. From 2.2, APIs are served at runtime. The files in plugins/ahmadfatoni/apigenerator/controllers/api/ from older versions are no longer used and can be deleted.
• Generator routes removed. The fatoni/generate/api, fatoni/update/api and fatoni/delete/api routes are gone. APIs are created and updated by saving the form in the backend.
• Stricter validation. API names may only contain letters, numbers and spaces and must start with a letter. Endpoints may only contain letters, numbers, dashes, underscores and slashes. The model must be one of the options in the dropdown.
• Correct 404 responses. Requesting a record that does not exist now returns a 404 JSON response instead of an empty 200.
• DELETE route. DELETE {endpoint}/{id} now works, and the old GET {endpoint}/{id}/delete route still works.
• Optional authentication. APIs stay public by default. Turn on Require Authentication to protect an API with a RainLab.User bearer token.