Download the PHP package appkr/api without Composer

RESTful HTTP API component for Laravel or Lumen based project

한국어 매뉴얼

INDEX

• 1. ABOUT
• 2. FEATURE
• 3. LARAVEL/LUMEN IMPLEMENTATION EXAMPLE
• 4. HOW TO INSTALL
• 5. CONFIG
• 6. TRANSFORMER
• 7. NESTING SUB-RESOURCE
• 8. APIs
• 9. BUNDLED EXAMPLE
• 10. LICENSE & CONTRIBUTION
• 11. CHANGELOG

1. ABOUT

A lightweight RESTful API builder for Laravel or/and Lumen project.

2. FEATURE

1. Provides Laravel/Lumen Service Provider for the league/fractal.
2. Provides configuration capability for the library.
3. Provides easy way of making transformed/serialized API response.
4. Provides make:transformer artisan command.
5. Provides examples, so that users can quickly copy & paste into his/her project.

3. LARAVEL/LUMEN IMPLEMENTATION EXAMPLE(How to use)

3.1. API Endpoint

Define RESTful resource route in Laravel way.

Lumen doesn't support RESTful resource route. You have to define them one by one.

3.2. Controller

The subsequent code block is the controller logic for /v1/books/{id} endpoint. Note the use cases of json() helper and transformer on the following code block.

4. HOW TO INSTALL

4.1. Composer.

4.2. Add the service provider.

4.3. [OPTIONAL] Publish assets.

The configuration file is located at config/api.php.

In Lumen we can manually create config/api.php file, and then activate the configuration at bootstrap/app.php like the following.

Done !

5. CONFIG

Skim through the config/api.php, which is inline documented.

6. TRANSFORMER

6.1. What?

For more about what the transformer is, what you can do with this, and why it is required, see this page. 1 transformer for 1 model is a best practice(e.g. BookTransformer for Book model).

6.2. Transformer Boilerplate Generator

Luckily this package ships with an artisan command that conveniently generates a transformer class.

• subject_ The string name of the model class.

• includes_ Sub-resources that is related to the subject model. By providing this option, your API client can have control over the response body. see NESTING SUB RESOURCES section.

  The option's signature is --include=Model,eloquent_relationship_methods[,isCollection].

  If the include-able sub-resource is a type of collection, like Book and Comment relationship in the example, we provide true as the third value of the option.

Note

We should always use double back slashes (\\), when passing a namespace in artisan command WITHOUT quotation marks.

A generated file will look like this:

7. NESTING SUB-RESOURCES

An API client can request a resource with its sub-resource. The following example is requesting authors list. At the same time, it requests each author's books list. It also has additional parameters, which reads as 'I need total of 3 books for this author when ordered by recency without any skipping'.

When including multiple sub resources,

In case of deep recursive nesting, use dot (.). In the following example, we assume the publisher model has relationship with somethingelse model.

8. APIs

The following is the full list of response methods that Appkr\Api\Http\Response provides. Really handy when making a json response in a controller.

8.1. Appkr\Api\Response - Available Methods

8.2. Appkr\Api\TransformerAbstract - Available Methods

8.3. helpers.php - Available Functions

9. BUNDLED EXAMPLE

The package is bundled with a set of example that follows the best practices. It includes:

• Database migrations and seeder
• routes definition, Eloquent Model and corresponding Controller
• FormRequest (Laravel only)
• Transformer
• Integration Test

Follow the guide to activate and test the example.

9.1. Activate examples

Uncomment the line.

9.2. Migrate and seed tables

Do the following to make test table and seed test data. Highly recommend to use SQLite, to avoid polluting the main database of yours.

9.3. See it works

Boot up a server.

Head on to GET /v1/books, and you should see a well formatted json response. Try each route to get accustomed to, such as /v1/books=include=authors, /v1/authors=include=books:limit(2|0):order(id|desc).

9.4. [OPTIONAL] Run integration test

Note

If you finished evaluating the example, don't forget to rollback the migration and re-comment the unnecessary lines at ApiServiceProvider.

10. LICENSE & CONTRIBUTION

MIT License. Issues and PRs are always welcomed.

11. CHANGELOG

v3.0.1

• Supports auto package discovery in Laravel 5.5 (No need to add ServiceProvider in config/app.php)

v3.0.0

• API not changed.
• Update league/fractal version to 0.16.0

v2.3.4

• jsonEncodeOption config added.

v2.3.3

• Appkr\Api\Http\UnexpectedIncludesParamException will be thrown instead of UnexpectedValueException when includes query params are not valid.

v2.3.0

• withCollection() now accepts Illuminate\Support\Collection.
• Fix bug at SimpleArrayTransformer.

v2.2.0

• Field name converting to snake or camel case depending on configuration (config('api.convert.key')).
• Date format converting depending on configuration (config('api.convert.date')).

v2.1.0

• TransformerAbstract::buildPayload method added to filter the list of response fields (Backward compatible).
• Artisan generated transformer template changed (Backward compatible).

v2.0.0

• TransformerAbstract's API changed.
• Partial response by query string feature removed. Instead we can explicitly set the list of attributes to respond in a Transformer's $visible or $hidden property.

v1.1.0 [buggy]

• Field grouping feature added for partial response conveniences.
• TransformerAbstract now throws UnexpectedValueException instead of Exception, when params or values passed by API client are not acceptable.

12. SPONSORS

• Thanks JetBrains for supporting phpStorm IDE.