mitchdav/laravel-versioned-api

A basic starter skeleton for working with versioned APIs using Laravel 5.3, Doctrine 2, Dingo 1.0 and JWT 0.5.

Laravel Versioned API

This is a skeleton for the Laravel framework which takes care of setting up a new project with Doctrine, Dingo and JWT. After installation you will have a working REST API which responds to requests for 3 different versions of the same API, and has authentication already built-in., _(*1)

Requirements

• PHP >= 5.6.4
• A database (MySQL, or any others supported by Laravel and Doctrine)
• Composer.

Dependencies

You have two options to get the skeleton setup:, _(*2)

1. Utilise Composer's create-project command by running the following command in the terminal:, _(*3)

   composer create-project mitchdav/laravel-versioned-api

2. Or clone the repo manually by running the following commands in the terminal:, _(*4)

   git clone https://github.com/mitchdav/laravel-versioned-api.git
   cd laravel-versioned-api
   composer install
   php -r "copy('.env.example', '.env');"
   php artisan key:generate
   php artisan jwt:generate

This will setup the project's dependencies, however you will still need to setup the database. You must first create a MySQL database, and then store its details in the .env file like so:, _(*5)

DB_DATABASE=mydatabase
DB_USERNAME=root
DB_PASSWORD=

To then setup the database we use Doctrine's helper command to build our schema and proxies., _(*6)

php artisan doctrine:schema:create
php artisan doctrine:generate:proxies

The system is now ready to receive requests made against it, however we don't have any users to login to the API with. To generate a test user, run the following command:, _(*7)

php artisan db:seed

This will output an email address and password you can use to login., _(*8)

Logging In

Make a POST request to /auth/authenticate with Content-Type set to application/json. The JSON structure should look like the following:, _(*9)

{
    "email": "{email address from previous command}",
    "password": "{password from previous command}"
}

If the response is successful, you will receive a token which you can use to make subsequent requests to the server, while remaining authenticated as the given user. To send through the token value send it in the Authorization header as follows:, _(*10)

Authorization: Bearer {token}

To retrieve the user details make a GET request to /auth/me and you will receive a request similar to the following:, _(*11)

{
    "id": 1,
    "email": "theodora39@example.net",
    "name": "Dillon Effertz",
    "job": "Roofer"
}

For further information about making requests to the server check the Dingo API Wiki., _(*12)

Developing The Server

As you make changes to the entities, you need to generate proxies for your entities, so that the system can load quickly for each request. To do this, run the following command in the terminal:, _(*13)

php artisan doctrine:generate:proxies

This will not be necessary unless you modify the entities as their proxies are already generated and committed., _(*14)

If your changes to an entity modify its database structure, you can persist this to the database by running the following command in the terminal:, _(*15)

php artisan doctrine:schema:update

Routes

Routes for your versions are available by looking at the routes file., _(*16)

Adding New Versions

The important files are all contained in the app/API folder. The project has 3 different versions of the same API, which is kept very simple to be as extendable as possible., _(*17)

When you would like to add a new version, you will need to follow this process:, _(*18)

1. Copy the whole previous version's folder into the app/API folder and give it a suitable name (for example, copy the app/API/V3 folder to app/API/V4)
2. Do a search and replace operation to update the folder's references from the previous version to the new version (for example, update all instances of V3 to V4 within the V4 folder)
3. Copy any existing routes from the previous version to the new version in the routes file
4. Update the config/api.php file to include the new version in the auth section
5. Update the .env file's API_VERSION variable to the new version
6. Make your changes to the API's new version (for example, add a new entity, or a field to an existing entity)

7. Run the following commands to update the database schema and proxies, _(*19)

   php artisan doctrine:generate:proxies
   php artisan doctrine:schema:update

8. Add routes to any new endpoints in the routes file

Removing Versions

To remove a version follow this process:, _(*20)

1. Remove the version's folder inside the app/API folder
2. Remove the routes for the removed version from the routes file
3. Remove the auth entry in the config/api.php file
4. Check that the .env file's API_VERSION variable is not set to the removed version