GitHub Repository

apiato

A) Apiato Application Installation

Apiato can be installed automatically with Composer (recommended) or manually (with Git or direct download):

1) Code Setup

1.A) Automatically via Composer

1) Clone the repo, install dependencies and setup the project:

Option 1: Latest stable release (7.3):

composer create-project apiato/apiato my-api

Option 2: Current LTS “Long-Term Support” stable release (7.2):

composer create-project apiato/apiato my-api ~7.2

Option 3: On going development branch “dev master” (unstable): This gives you features from the upcoming releases. But you need to keep syncing your project with the upstream master branch and running composer update when changes occurs.

composer create-project apiato/apiato my-api dev-master

2) Edit your .env variables to match with your environment (Set Database credentials, App URL, …).

3) Continue from 2) Database Setup below.

1.B) Manually

You can download the Code directly from the repository as .ZIP file or clone the repository using Git (recommended):

1) Clone the repository using Git:

git clone https://github.com/apiato/apiato.git

2) Install all dependency packages (including Containers dependencies):

composer install

3) Create .env file and copy the content of .env.example inside it.

cp .env.example .env

Check all the variables and edit whatever you want.

4) Generate a random key APP_KEY

php artisan key:generate

5) delete the .git folder from the root directory and initialize your own with git init.

2) Database Setup

1) Migrate the Database:

b. Run the migration artisan command:

php artisan migrate

2) Seed the database with the artisan command:

php artisan db:seed

3) Optional. By default Apiato seeds a “Super User”, given the default admin role (the role has no Permissions set to it).

To give the admin role, access to all the seeded permissions in the system, run the following command php artisan apiato:permissions:toRole admin at any time.

NOTE: if you are using Laradock, you need to run those commands from the workspace Container, you can enter that container by running docker-compose exec workspace bash from the Laradock folder.

3) OAuth 2.0 Setup

1) Create encryption keys to generate secure access tokens and create “personal access” and “password grant” clients which will be used to generate access tokens:

php artisan passport:install

4) Documentation Setup

If you are planning to use ApiDoc JS then proceed with this setup, else skip this and use whatever you prefer:

1) Install ApiDocJs using NPM or your favorite dependencies manager:

Install it Globally with -g or locally in the project without -g

npm install apidoc -g

Or install it by just running npm install on the root of the project, after checking the package.json file on the root.

2) run php artisan apiato:docs

Behind the scene apiato:docs is executing a command like this apidoc -c app/Containers/Documentation/ApiDocJs/public -f public.php -i app -o public/api/documentation.

Visit API Docs Generator for more details.

5) Testing Setup

1) Open phpunit.xml and make sure the environments are correct for your domain.

2) run the tests

vendor/bin/phpunit

B) Development Environment Setup

You can run Apiato on your favorite environment. Below you’ll see how you can run it on top of Vagrant (using Laravel Homestead) or Docker (using Laradock). We’ll see how to use both tools and you can pick one, or you can use other options like Larvel Valet, Laragon or even run it directly on your machine.

A.1) Using Docker (with Laradock)

Laradock is a Docker PHP development environment. It facilitate running PHP Apps on Docker.

1) Install Laradock.

2) Navigate into the laradock directory:

cd laradock

This directory contains a docker-compose.yml file. (From the LaraDock project).

2.1) If you haven’t done so, rename env-example to .env.

cp env-example .env

3) Run the Docker containers:

docker-compose up -d nginx mysql redis beanstalkd

4) Make sure you are setting the Docker IP as Host for the DB and Redis in your .env file.

5) Add the domain to the Hosts file:

5.1) Open the hosts file on your local machine /etc/hosts.

We’ll be using apiato.dev as local domain (you can change it if you want).

5.2) Map the domain and its subdomains to 127.0.0.1:

127.0.0.1  apiato.dev
127.0.0.1  api.apiato.dev
127.0.0.1  admin.apiato.dev

If you’re using NGINX or Apache, make sure the server_name (in case of NGINX) or ServerName (in case of Apache) in your the server config file, is set to the following apiato.dev api.apiato.dev admin.apiato.dev. (Also don’t forget to set your root or DocumentRoot to the public directory inside apiato apiato/public).

A.2) Using Vagrant (with Laravel Homestead)

1) Configure Homestead:

1.1) Open the Homestead config file:

homestead edit

1.2) Map the api.apiato.dev domain to the project public directory - Example:

sites:
	- map: api.apiato.dev
  	  to: /{full-path-to}/apiato/public

1.3) You can also map other domains like apiato.dev and admin.apiato.dev to other web apps:

	- map: apiato.dev
  	  to: /{full-path-to}/clients/web/user
	- map: admin.apiato.dev
  	  to: /{full-path-to}/clients/web/admin

Note: in the example above the /{full-path-to}/clients/web/*** are separate apps, who live on their own repositories and in different folder then the Apiato one. If your Admins, Users or other type of Apps are within Apiato, then you must point them all to the Apiato project folder /{full-path-to}/apiato/public. So in that case you would have something like this:

    - map: api.apiato.dev
      to: /{full-path-to}/apiato/public
    - map: apiato.dev
      to: /{full-path-to}/apiato/public
    - map: admin.apiato.dev
      to: /{full-path-to}/apiato/public

2) Add the domain to the Hosts file:

2.1) Open the hosts file on your local machine /etc/hosts.

We’ll be using apiato.dev as local domain (you can change it if you want).

2.2) Map the domain and its subdomains to the Vagrant IP Address:

192.168.10.10   apiato.dev
192.168.10.10   api.apiato.dev
192.168.10.10   admin.apiato.dev

If you’re using NGINX or Apache, make sure the server_name (in case of NGINX) or ServerName (in case of Apache) in your the server config file, is set to the following apiato.dev api.apiato.dev admin.apiato.dev. (Also don’t forget to set your root or DocumentRoot to the public directory inside apiato apiato/public).

2.3) Run the Virtual Machine:

homestead up --provision

If you see No input file specified on the sub-domains!
try running this command homestead halt && homestead up --provision.

A.3) Using something else

If you’re not into virtualization solutions, you can setup your environment directly on your machine. Check the software’s requirements list.

C) Play

Now let’s see it in action

1.a. Open your web browser and visit:

1.b. Open your HTTP client and call:

2) Make some HTTP calls to the API:

To make the calls you can use Postman, HTTPIE or any other tool you prefer.

Let’s test the (user registration) endpoint http://api.apiato.dev/v1/register with cURL:

curl -X POST -H "Accept: application/json" -H "Cache-Control: no-cache" -F "email=mahmoud@zalt.me" -F "password=so-secret" -F "name=Mahmoud Zalt" "http://api.apiato.dev/v1/register"

You should get response similar to this:

Access-Control-Allow-Origin  ...
Cache-Control  ...
Connection  keep-alive
Content-Language  en
Content-Type  application/json
Date  Wed, 11 Apr 2000 22:55:88 GMT
Server  nginx
Transfer-Encoding  chunked
Vary  Origin
X-Powered-By  PHP/7.7.7
X-RateLimit-Limit  30
X-RateLimit-Remaining  29

{
  "data": {
    "object": "User",
    "id": 77,
    "name": "Mahmoud Zalt",
    "email": "apiato@mail.com",
    "confirmed": null,
    "nickname": "Mega",
    "gender": "male",
    "birth": null,
    "social_auth_provider": null,
    "social_id": null,
    "social_avatar": {
      "avatar": null,
      "original": null
    },
    "created_at": {
      "date": "2017-04-05 16:17:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "updated_at": {
      "date": "2017-04-05 16:17:26.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "roles": {
      "data": []
    }
  }
}