Download the PHP package racoon/api without Composer

Racoon API Framework

Racoon is a basic API framework designed to make it quick and easy to put together a simple PHP API. View the documentation.

Getting Started

Autoloading

Racoon depends on autoloading provided by Composer. If you do not use Composer then you will have to set up your own PSR autoloader or start using Composer.

Quickstart

Create an application, add some routes and run the application.

index.php

/path/to/my_routes.php

/MyApp/Users.php

Routing

Racoon uses racoon/router to deal with routing.

Defining where routes are stored

Routes need to be added in a routes file, which should be added to the Router.

If you want to store routes in multiple locations you can do it as follows.

If you define multiple route locations, they will be included/added in the same order as you define them.

Setting up routes

Inside one of the route files that have been added to the router you need to define your routes in the following format.

Handler Namespaces

If like me, all of your application controllers are under one namespace, you can use the following method to simplify your routes file.

Before:

After:

HTTP Request Method

The HTTP Request Method(s) that the route should match. This can be any HTTP request type such as GET or POST.

Can be a string or an array of strings.

Request URI

The request URI that the route should match.

You can define the request URI in multiple ways.

For more information see the FastRoute Route Docs

Any wildcards/placeholders defined here will be passed into the Controller/Handler method.

Handler String

The handler string defines the class and method that should be executed should the current request match a route.

The required format is \MyApp\Users@list where \MyApp\Users is the full class name including the namespace, and list is the method inside of that class which you want to be executed.

Controllers

Your controllers should extend \Racoon\Api\Controller.

The Request

When your Controller is first instantiated it won't have access to the Request object, however, you can create a public function setupRequest() which will be called directly after adding the Request to the Controller. This will then allow you to set up your Controller based on any parameters stored in the Request.

Your Response

You shouldn't echo anything from your Controller. Instead, your method should return something and let Racoon deal with it.

Response Formatter

Racoon allows you choose how your response is to be formatted. By default the \Racoon\Api\Response\Format\JsonFormatter will be used.

You are free to use any Formatter you want, as long as it implements \Racoon\Api\Response\Format\FormatterInterface.

To use a different Formatter just do the following, where \Racoon\Api\Response\Format\JsonFormatter is your chosen Formatter.

Returning Errors

In order to easily provide an error response back for a request all you need to do is throw an \Racoon\Api\Exception.

If you extend \Racoon\Api\Exception however, you can simply things massively. To demonstrate this we can take a look at the \Racoon\Api\AuthenticationException.

This means that we can display an error as follows.

Authentication

By default Racoon doesn't authenticate any requests that come into your application, but it can be easily set up.

You can override the authentication method by setting a new Authenticator before running the app.

Available Authenticators

NoAuthenticator

This Authenticator will allow any request through as it does no authentication.

ApiKeyAuthenticator

This Authenticator allows you to specify an array of valid API Keys which it will consider valid.

Creating Custom Authenticators

You are free to create your own Authenticator, just make sure it implements \Racoon\Api\Auth\AuthInterface.

Schema

The have the ability to create a Schema to easily validate incoming requests, as well as provide some basic documentation to the end user when they are trying out API requests.

A Schema is made up of one or more Items and will be valid if all items pass their constraints.

The following should be run from a Controller and will set up and validate the Schema. Username will need to be a string between 2 and 20 characters, and password will need to be a string with at least 6 characters.

You can build more robust rules by doing something like this... Username must be a string between 2 and 4 characters, OR between 10 and 12 characters.

The validation is done using TomWright/Validator so for more information please see the related GitHub page.

Request

The Request object contains most of the information about the current request such as the request URI, the data provided in the request, as well as the current Schema. The Request object can also be accessed from your Controller using $this->getRequest().

If for some reason you want to expand on the functionality of Racoon so as to store more data about the Request you can extend \Racoon\Api\Request and then tell Racoon to use your Request class instead.

Fetching Request Data

You can get the input data by using $request->getRequestData(), however there are also 2 helper methods to streamline things for you a little in the Controller.

Using the API

Using the API is simple.

All data is passed to Racoon as JSON in a GET or POST variable named json.

If you want to send data under a different name rather than json, you can do the following.

Let's say we have got things set up for mydomain.com, and we have a route that matches /users/get with a required item of user_id. If we were to make a GET request, the request should look something like this....

Notice that the request is in it's own object inside of json. This allows you to separate authentication/test parameters from the actual data you want to use in your Controller.

E.g.

Response

When working with Racoon you will always get a formatted response that looks something like the following (depending on which Response Formatter you use).

Success

True if no Exception was thrown. False if an Exception was thrown.

Message

The message set by the Controller, or the Exception message.

Schema

The Schema that was set up in the Controller.

Received

The data that was sent to the API.

Time Elapsed

The time (in ms) that it took for the API request to be processed.

Response

The data that was returned by the Controller.

HTTP Response Code

In addition to the above, if an Exception is thrown that is set up to return the error, the code of that Exception will be used to set the HTTP response code.