Skip to main content

3 Bundles to get started with REST in Symfony 2 and some tips

| (about a 5 minute )

"I found out that you guys just build an amazing mobile app for your e-commerce venture, I heard you are using Symfony 2 for your back-end APIs. How did you make it that fast?" This is not very different that what I was asked some months back. The answer is we use a Service Oriented Architecture (SOA) where all back-end service follow the REST architecture to communicate with all the clients. The client can be built in any language as longs a they can do HTTP calls. Lets look at what Symfony 2 bundles you can use to build a similar scalable, fast and cacheable REST APIs.

I assume that you have some experience with Symfony 2 including how to use composer to download dependent libraries/bundles.

What is REST

REST, short form for Representational state transfer is a resource based client and server communication protocol which is stateless and cacheable. It is an abstraction over HTTP communication where emphasis is given on uniform interface to make the communication structured and consistent. This video describes the constraints of REST and explains what it is or read a simpler one.

REST is a lightweight substitute to older ways of doing web services like Remote Procedure Call (RPC) and Simple Object Access Protocol (SOAP). Basically communication in REST happens in light weight format like JSON which makes it fast.

Describing REST involves having knowledge if the HTTP methods (verbs) like GET, POST, PUT, DELETE. Before proceeding further knowing what are they used for will be essential. There is also lots of fuss about how to name resources (and corresponding URIs) but rather than doing things by the book making it logical and practical can be the best solution.

RESTing With Symfony 2

Symfony is a very loosely coupled framework which has lots of useful components structured in easily plug-able bundles. Here are 3 useful public Symfony 2 bundles for your next project using REST with Symfony.

FOSRestBundle

The FOSRestBundle provides a solid foundation to start building RESTful services in Symfony 2. It can provide with automated routing for resources (probably doctrine entity if you use doctrine). It provides a very good base for a format (JSON/HTML/XML) independent view layer. 

If you want to be able to encode or decode multiple format FOSRestBundle recommends using JMSSerializerBundle. The serializer bundle is like glove on the hand with FOSRestBundle to give out response in JSON/HTML/XML. Please go through the documentation very well and for custom routing you can use Symfony routing and not the one provide by FOSRestBundle. It is one of the most popular bundles in KNPBundles and has been downloaded more than 784K times.

NelmioApiDocBundle

NelmioApiDocBundle is a boon when developing REST web services on Symfony2. The bundle enables clean documentation of all API end points by just using some structured annotation. There are at least 2 amazing benefits using this bundle, first you can give the link to the docs (generally /api/doc) to anyone who wants to implement the REST API you have created. Second while developing you can test your API with the sandbox feature provided by this useful bundle, if you use the annotations correctly linking the involved forms.

Restricting sandbox with user access might be a good feature to add on on this bundle. Reading the full documentation is highly encouraged. It is also a very popular bundle with 473K downloads till date.

LexikJWTAuthenticationBundle

As discussed REST is stateless, so for authentication you have to opt for some mechanism that can be communicate with each request. You can go for something like Oauth or use JSON Web Signature (JWS). There is already a public bundle the LexikJWTAuthenticationBundle using the JOSE library built at Namshi. It is recommended that you read about JWS and JSON Web Token (JWT) before using this bundle. It can be used by putting the token as a cookie for each request.

It will enable role based access to your API end points, lets say you want normal users to create users and only admin users to update/delete users that will be easily possible using this bundle than trying to generate a time limited key or some other type of authentication. Yes, reading the documentation of the bundle will help you achieve the desired output.



I hope these modules will come in handy when you start your REST Api with symfony. For more features and to leverage REST to the fullest you can take a look at BazingaHateoasBundle and TemplatedUriBundle.

Other Tips

Some other things you can consider when building a REST based API with Symfony 2 are:
  1. Use the validation groups in Symfony 2 and keep all the validation conditions as annotation in the Entity itself than at multiple places.
  2. Keep the handing of forms central, though you will not show any HTML forms for the purpose of validation use the Symfony forms on top of the entities and link them to controllers which expose the end points.
  3. Use the HTTP status code wisely like when a resource is created its not 200 OK its 201 Created, when you are paging results 206 will make for sense and if the user sent bad data 400 Bad Request is better.
  4.  Think how will you version your API early when you develop your API if today you use /api/V1 how will you use api/V2 and what will be its consequences.
  5. Last but not he least be liberal on what you accept and strict on what you give out.
All in all Symfony is a great framework and doing REST in Symfony though not a piece of cake but is challenging yet rewarding. 

Comments