Skip to main content
Version: Next 🚧

Installation

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.

tip

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.

info

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:

tip

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:

  1. Open your .env file and modify the API domain by updating the API_URL value from http://api.apiato.test to http://apiato.test to remove the subdomain.
  2. In the app/Ship/Configs/apiato.php configuration file:
    • Set the prefix to api/.
    • Set enable_version_prefix to false.

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)

API (HTTP Client)

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: