Installation
Introduction
Apiato is a PHP framework built on top of Laravel, designed to help you build scalable and maintainable APIs quickly and efficiently. It provides a set of tools and patterns to solve common problems in API development, allowing you to focus on building your application instead of reinventing the wheel.
With Apiato, you get the following benefits:
- Rapid Development: Built on Laravel, it leverages Laravel's strengths and adds additional features to speed up API development.
- Scalability: Designed for building enterprise-grade APIs that can scale with your application's growth.
- Maintainability: Encourages clean, organized, and reusable code through its unique "Porto" architectural pattern.
Whether you're building a small project or a large, complex API, Apiato can help you get there faster and with fewer headaches.
Your First Apiato Project
Before creating your first Apiato project, you should ensure that your local machine has PHP and Composer installed. If you are developing on macOS, PHP and Composer can be installed via Homebrew.
After you have installed PHP and Composer, you may create a new Apiato project via the Composer create-project command:
composer create-project apiato/apiato example-app --no-scripts
Development Environment Setup
You can run Apiato in any environment that you can run Laravel.
Visit Laravel Installation for more details.
Initial Configuration
All the configuration files for the Laravel framework are stored in the config
folder
and all the configuration files for the Apiato framework are stored in app/Ship/Configs
.
Each option is documented, so feel free to look through the files and get familiar with the options available to you.
Apiato needs almost no additional configuration out of the box.
You are free to get started developing!
However, you may wish to review the app/Ship/Configs/apiato.php
file and its documentation.
It contains several options that you may wish to change, according to your application.
Environment Based Configuration
Since many of Apiato configuration option values may vary
depending on whether your application is running on your local machine or on a production web server,
many important configuration values are defined using the .env
file that exists at the root of your application.
Your .env
file should not be committed to your application's source control,
since each developer / server using your application could require a different environment configuration.
Furthermore, this would be a security risk in the event an intruder gains access to your source control repository,
since any sensitive credentials would get exposed.
For more information about the .env
file and environment based configuration,
check out the Laravel full configuration documentation.
Databases & Migrations
Now that you have created your Apiato application, you probably want to store some data in a database.
By default,
your application's .env
configuration file specifies
that Apiato will be interacting with a MySQL database and will access the database at 127.0.0.1
.
If you are developing on macOS and need to install MySQL, Postgres,
or Redis locally, you may find it convenient to utilize DBngin
.
If you do not want to install MySQL or Postgres on your local machine, you can always use a SQLite database. SQLite is a small, fast, self-contained database engine. To get started, create a SQLite database by creating an empty SQLite file. Typically, this file will exist within the database directory of your Apiato application:
touch database/database.sqlite
Next, update your .env
configuration file to use Laravel sqlite database driver.
You may remove the other database configuration options:
+ DB_CONNECTION=sqlite
- DB_CONNECTION=mysql
- DB_HOST=127.0.0.1
- DB_PORT=3306
- DB_DATABASE=homestead
- DB_USERNAME=homestead
- DB_PASSWORD=secret
Once you have configured your SQLite database, you may run your application's database migrations, which will create your application's database tables:
php artisan migrate
Default User, Roles & Permissions
Apiato includes a default (Super Admin) user along with predefined roles and permissions.
To populate the database with these default values, you may execute the db:seed
command.
php artisan db:seed
Default User Credentials:
- email: [email protected]
- password: admin
You can create a new admin user using the apiato:create:admin
interactive command:
php artisan apiato:create:admin
Authentication Configuration
Visit Authentication for more details.
Directory Configuration
Apiato should always be served out of the root of the "web directory" configured for your web server. You should not attempt to serve a Apiato application out of a subdirectory of the "web directory". Attempting to do so could expose sensitive files present within your application.
Subdomain and API Version Prefix
By default, Apiato uses api
as a subdomain for all endpoints and adds only the API version as a prefix,
resulting in URLs like api.apiato.test/v1
.
However, you can change this behavior.
For example, if you'd like to achieve urls like apiato.test/api/
, follow these steps:
- Open your
.env
file and modify the API domain by updating theAPI_URL
value fromhttp://api.apiato.test
tohttp://apiato.test
to remove the subdomain. - In the
app/Ship/Configs/apiato.php
configuration file:- Set the
prefix
toapi/
. - Set
enable_version_prefix
tofalse
.
- Set the
Generating API Documentation
Apiato includes a convenient Documentation Generator package that utilizes ApiDocJs for API documentation generation.
To get started, install ApiDocJs using NPM or your preferred dependency manager:
npm install
Next, generate the API documentation by executing the following command:
php artisan apiato:apidoc
Let's Play
To witness Apiato in action, assuming you are using the default Subdomain and API Version Prefix configuration, you should be able to access the following URLs and see the following results:
Web (Browser)
- http://apiato.test -> Apiato welcome page.
API (HTTP Client)
- http://api.apiato.test ->
"Welcome to Apiato"
- http://api.apiato.test/v1 ->
"Welcome to Apiato (API V1)"
Next Steps
Now that you have created your Apiato project, you may be wondering what to learn next. If you're looking for a place to start, you should check out the following resources: