Wallogit.com
2017 © Pedro Peláez
A useful bundle for easily creating RESTful resources.
This is a very small but powerful Symfony2 bundle for quickly building RESTful resources (specifically, HTTP APIs)., (*1)
Installation is relatively easy. It requires three steps. Start by adding the right dependency to your composer.json file and install the new bundle., (*2)
"brightmarch/restful-bundle": "1.0.0"
You can safely assume that what is in master is always up to date., (*3)
$ composer.phar install brightmarch/restful-bundle
Once installed, add it to app/AppKernel.php in the main $bundles array. You do not want this to be part of the dev system only., (*4)
$bundles = array(
new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
// ... other bundles ... //
new Brightmarch\Bundle\RestfulBundle\BrightmarchRestfulBundle(),
);
Installation is complete, you are now ready to begin building a RESTful resource., (*5)
To start, you will most likely want to start with your own bundle. Each resource that you want to work with this bundle must extend the Brightmarch\Bundle\RestfulBundle\Controller\RestfulController controller., (*6)
resourceSupports('application/json', 'application/xml', 'text/html');
$accounts = $this->get('doctrine')
->getManager()
->getRepository('SampleAppBundle:Account')
->findAll();
// The type of the view will automatically
// be found based on the Accept header.
$parameters = [
'accounts' => $accounts
];
return $this->renderResource('SampleAppBundle:Accounts:accounts', $parameters);
}
}
```
You must describe what content types this resource supports. This means if a client sends an Accept header with a content type this resource does not accept, a `406 Unacceptable` response will be returned. Because this resource supports three content types, you must have three different views: accounts.json.twig, accounts.xml.twig, and accounts.html.twig.
### index.json.twig
```javascript
{% autoescape false %}
[
{% for account in accounts %}
{
"id": {{ account.getId|json_encode }},
"name": {{ account.getName|json_encode }}
}
{% endfor %}
]
{% endautoescape %}
```
### index.xml.twig
```xml
<accounts>
{% for account in accounts %}
<account>
<id>{{ account.getId }}</id>
<name>{{ account.getName }}</name>
</account>
{% endfor %}
</accounts>
<!doctype html>
<html>
<head>
<title>Accounts Resource</title>
</head>
<body>
<ul>
{% for account in accounts %}
<li>{{ account.getName }}</li>
{% endfor %}
</ul>
</body>
</html>
A slightly more advanced controller might find an entity and render it. You want to render it in the format requested. You would simply create the templates for those formats. Don't forget that resources should link to one another and each other, if necessary. Here is a sample template for an Account., (*7)
{% autoescape false %}
{
"id": {{ account.getId }},
"created_at": {{ account.getCreatedAt|format_date|json_encode }},
"updated_at": {{ account.getUpdatedAt|format_date|json_encode }},
"name": {{ account.getName|json_encode }},
"identifier": {{ account.getIdentifier|json_encode }},
"email": {{ account.getEmail|json_encode }},
"lang": {{ account.getLang|json_encode }},
"_links": [
{
"rel": "self",
"url": {{ url('sample_app_view_account', { 'id': account.getId })|json_encode }}
},
{
"rel": "alt",
"url": {{ url('sample_app_view_account_identifier', { 'identifier': account.getIdentifier })|json_encode }}
}
]
}
{% endautoescape %}
You will notice there are two _links records. One points directly back to itself, and the other provides an alternative URL to the same resource., (*8)
This bundle supports handling HTTP errors properly. It comes with several exceptions for handling errors. They include:, (*9)
HttpBadSyntaxException
HttpMethodNotAllowedException
HttpNotAcceptableException
HttpConflictException
HttpUnsupportedMediaTypeException
HttpNotExtendedException
HttpNotFoundException
HttpUnauthorizedException
You are responsible for rendering your errors. There is a default template located in Resources/views/Restful/error.json.twig. You should familiarize yourself with catching kernel exceptions in Symfony using an Event Listener to automatically return all errors as a RESTful response. The error response template looks like this:, (*10)
{% autoescape false %}
{
"httpCode": {{ httpCode }},
"message": {{ message|json_encode }}
}
{% endautoescape %}
The HTTP code will also be sent back as part of the response payload. For example, making this request to the resource above would result in a 406 error:, (*11)
$ curl -v -H "Accept: invalid/type" http://example.com/
< HTTP/1.1 406 Not Acceptable
< Content-Length: 195
< Content-Type: application/json; charset=utf-8
<
{
"httpCode": 406,
"message": "This resource can not respond with a format the client will find acceptable. This resource supports: [application\/json, application\/xml, text\/html]."
}
If the error code of an exception can not be determine, the default 500 error code is used. More HttpException classes will be added as needed., (*12)
The MIT License (MIT), (*13)
Copyright (c) 2012-2014 Vic Cherubini, Bright March, LLC, (*14)
A useful bundle for easily creating RESTful resources.
MIT
api rest http restful