dingo API

Dingo/API is a popular open source project that provides us with a set of tools to help us easily and quickly build our own API.

This starter package provides a sane configuration for dingo/API with optional JWT support.
Note that it's up to you to explore additional configuration options and functionalities provided by dingo/API on their wiki as only the basics have been pre-configured here.

API Setup

The api prefix is configured to be /api/, this means all your endpoints will be preceded by /api/.
This is defined in your .env file and effectively active in your config/api.php. Feel free to explore other options, like setting a subdomain instead of a prefix.

🚧

Debugging

You can enable debug mode on the API with the API_DEBUG=true entry in your .env file, in case you'd output the stacktrace of an error.

API Versionning

The default version for the API is set to v1.
This is very helpful if you'd like to support backward compatibility for some endpoints on your API.
This default verison is applied in app/Providers/RouteServiceProvider.php, since most users start off with just 1 version so it was moved out of your way from the routes file. Feel free to remove it from there and add it manually to specific routes in your routes.php. You can also create a routes file per version. It's all up to you.

Content Negotiation

You're probably wondering: how does the client ask for a specific version?
This happens through content negotiation, which is the Accept header sent with every request. Here's the Accept header that you need to send to specify a json response format and version v1:
Accept: application/x.laravel.v1+json

You can see these values in your config/api.php. Feel free to change them (and update them in your Restangular configuration ).
Although this header is not required, it has been configured in your Restangular configuration by default. However, it is recommended that you enable Strict Mode on your staging & production environment using API_STRICT=true in your .env file.
Strict mode would force the client to send the Accept header.
Forcing the client to send the accept header will make sure that other potential users of your API (other developers maybe?) are using the correct version of your API so they won't be affected when you release a new version (say v2).

So as a wrap up, content negotiation allows the client to request a specific version and a specific return type from the API.

📘

You don't have to enable strict mode locally, as it'll make testing a bit painful.