README

slim-json-api

WARNING: this is only q maintained Fork of "https://github.com/entomb/slim-json-api"

This is an extension to the SLIM framework to implement json API's with great ease.

Installation

Using composer you can add use this as your composer.json

{
  "require": {
    "slim/slim": "2.*",
    "voku/slim-json-api": "2.*"
  }
}

Usage

To include the middleware and view you just have to load them using the default Slim way. Read more about Slim Here (https://github.com/codeguy/Slim#getting-started)

    require 'vendor/autoload.php';

    $app = new \Slim\Slim();

    $app->view(new \voku\slim\JsonApiView());
    $app->add(new \voku\slim\JsonApiMiddleware());

.htaccess sample

Here's an .htaccess sample for simple RESTful API's

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [QSA,L]

example method

all your requests will be returning a JSON output. the usage will be $app->render((int)$HTTP_CODE, (array)$DATA);

example code

$app->get('/', function() use ($app) {
  $app->render(
      200,
      array(
          'msg' => 'welcome to my API!',
      )
  );
});

example output

{
  "msg":"welcome to my API!",
  "error":false,
  "status":200
}

Errors

To display an error just set the error => true in your data array. All requests will have an error param that defaults to false.

$app->get('/user/:id', function($id) use ($app) {

  // your code here

  $app->render(
    404,
    array(
        'error' => TRUE,
        'msg'   => 'user not found',
    )
  );
});

{
  "msg":"user not found",
  "error":true,
  "status":404
}

You can optionally throw exceptions, the middleware will catch all exceptions and display error messages.

$app->get('/user/:id', function($id) use ($app) {

  // your code here

  if (...) {
    throw new Exception("Something wrong with your request!");
  }
});

{
  "error": true,
  "msg": "ERROR: Something wrong with your request!",
  "status": 500
}

Embedding response data and metadata in separate containers

It is possible to separate response metadata and business information in separate containers.

To make it possible just init JsonApiView with containers names

require 'vendor/autoload.php';

$app = new \Slim\Slim();

$app->view(new \voku\slim\JsonApiView("data", "meta"));
$app->add(new \voku\slim\JsonApiMiddleware());

Response

{
  "data":{
    "msg":"welcome to my API!"
  },
  "meta":{
    "error":false,
    "status":200
  }
}

routing specific requests to the API

If your site is using regular HTML responses and you just want to expose an API point on a specific route, you can use Slim router middlewares to define this.

function apiRequest() {
  $app = \Slim\Slim::getInstance();
  $app->view(new \voku\slim\JsonApiView());
  $app->add(new \voku\slim\JsonApiMiddleware());
}

$app->get('/home', function() use ($app){
  // regular html response
  $app->render("template.tpl");
});

$app->get('/api', 'apiRequest', function() use ($app){
  // this request will have full json responses

  $app->render(
    200,
    array(
        'msg' => 'welcome to my API!',
    )
  );
});

Middleware

The middleware will set some static routes for default requests. if you dont want to use it, you can copy its content code into your bootstrap file.

IMPORTANT: remember to use $app->config('debug', false); or errors will still be printed in HTML

voku / slim-json-api

Maintainers

Details