Skip to content

Latest commit

 

History

History
90 lines (61 loc) · 3.7 KB

Api.markdown

File metadata and controls

90 lines (61 loc) · 3.7 KB

Api

The Epiphany PHP Framework

Understanding the Api module

You can see an example in the examples directory. This module depends on Route and supports regular expressions in the same way.

If you've ever wanted to create an API and use it to build your application then read on. The Api module makes it easy to define, expose and consume an API for your application.

Epi::init('api');
getApi()->get('/version.json', array('Api', 'version'), EpiApi::external);
getApi()->get('/users.json', array('Api', 'users'), EpiApi::external);
getRoute()->get('/users', array('Site', 'users'));
getRoute()->run();

The first thing we need to do is include the api module using Epi::init. After that we can begin defining our API routes. We define a route to return the API version and another to list all our users. Finally we call getRoute()->run() method which sets up the routes. Public routes will be accessible via HTTP/PHP while private routes are accessible only using PHP.

Creating an API for internal consumption

Since you're already in a PHP context you'll want to access your API natively through PHP. Epiphany makes it easy to call your API endpoints directly without having to make an HTTP call.

In this example we'll continue from the example we started above and define the version and users methods. We'll then use that API to create a webpage that renders users in an ordered list.

class Api {
  public static function version() {
    return '1.0';
  }

  public static function users() {
    $users = array(
      array('username' => 'jmathai'),
      array('username' => 'stevejobs'),
      array('username' => 'billgates')
    );
    return $users;
  }
}

Next we can define the class method to display a list of users. From PHP we can natively call our API to get the list of users by using invoke().

class Site {
  public static function users()
  {
    $users = getApi()->invoke('/users.json');
    echo '<ul>';
    foreach($users as $user) {
      echo "<li>{$user['username']}</li>";
    }
    echo '</ul>';
  }
}

Accessing your API externally over HTTP

If you access /version.json then you'll get the results from Api::version and similar for /users.json.

curl http://localhost/version.json
"1.0"

curl http://localhost/users.json
[{"username":"jmathai"},{"username":"stevejobs"},{"username":"billgates"}]

Without having to add any code you have a RESTful HTTP API.

Permissioning your API endoints

The purpose of the api module is to enable you to build your application on top of a defined API. Obviously you won't want all of your API endpoints to be publicly available over HTTP. For this reason you'll want to specify the visibility on your routes.

For security purposes the visibility defaults to private. However, you can specify this when you define the route. If we wanted our /version.json endpoint to remain public while making /users.json private we'd define the routes as below.

getApi()->get('/version.json', array('Api', 'version'), EpiApi::external);
getApi()->get('/users.json', array('Api', 'users'), EpiApi::internal);

Since API endpoints are private by default you do not have to specify EpiApi::internal.

Loading your API routes from an external file

Not yet implemented.