Core Documentation

Core Documentation

Incomplete

1. Controllers
2. Self Documentation
3. Formatters
4. Exceptions

Controllers

Controllers serve two functions.

1. To provide endpoints.
2. To route to other controllers.

Endpoints

Endpoints are the bread an butter of an api, they provide the functionality. In Aye Aye, endpoints are specially named methods inside controllers. The naming convention works like this [verb][Name]Endpoint.

1. The [verb] is an HTTP verb or method. For example get and post are valid verbs. These are written in lower case.
2. The [Name] is the name of your endpoint as it will appear in the url. The is must start with a capital letter and if the endpoint is multiple words that you'd like to separate, then each new word should be capitalised.
3. The word Endpoint is added to the end to tell Aye Aye that this is an endpoint, and not some other type of method, you do not want visible and accessible to the outside world.

Endpoint methods should return the data you want the user to receive.

Example

public function getHelloWorldEndpoint(...) {
   ...
}

In the example above, we have created an endpoint called HelloWorld. It uses the get verb, so you can access it by sending a get request to /hello-world. Notice the casing of the name caused the url to break into a readable

Controllers

Aye Aye uses a single controller as a starting point, all other controllers must be accessible via that controller. We do this by adding methods that using the following naming convention [name]Controller.

1. The [name] is the name of your controller as it will appear in the url. The is must start with a capital letter and if the endpoint is multiple words that you'd like to separate, then each new word should be capitalised.
2. The word Controller is added to the end to tell Aye Aye that this method provides access to another controller. It will be listed separately from the current controllers endpoints.

Controller methods must return an instance of another controller.

Example

public function fooBarController() {
    returns new FooBar();
}

This example will allow access to the FooBar Controllers endpoints and sub controllers via the url /foo-bar.

Exceptions

Aye Aye includes a special Exception designed to provide more useful information to your end users. Simply, they can be given two messages, one for you which should be logged, and one to send the user. Furthermore, the exceptions code will be carried forward as an HTTP status. Here's the constructor:

public function __construct($publicMessage = '', $code = 500, $systemMessage = '', \Exception $previous = null)

The important thing to note here is that the first message is now public. This message can be used to inform the user of what went wrong. The code defaults to 500, which will be translated to an Internal Server Error.

Example

// use \AyeAye\Api\Exception;

public function getExceptionEndpoint() {
    throw new Exception(
        'Hello Exception',    // Data returned to user
        500,                  // The HTTP status code
        'User hit Exception', // Message for your logs
        null                  // Any exception can be added here
    );
}