Symfony a RESTFul app: REST Levels 0, 1, 2 ( NelmioApiDocBundle )

In the previous post we set up a basic symfony project aiming to develop a RESTFul solution.

Its nice to develop great applications with the tools we love, been well supported and with an strong community behind it, its even more satisfactory to develop this apps real fast and with good software architecture in mind so future contributors can get to theirs work with less effort. But what happens with our clients?

In this case the clients of RESTFul apps are also developers that need to integrate web based SPA or mobile applications. We need to take care of those clients too and documentation its a really important in those cases. Not just documentation, but a well described and updated documentation.

As always all the code on this series can be found on this github repository under the symfony2_restful_example branch.

NelmioApiDocBundle:

This is another great bundle delivered from the community to the community. It expose configurations and enable features that allow us to deliver REST API Documentation in a really simple and nicest way. The documentation for this bundle can be found on this page.

After installation and configuration, following the instructions on the bundle documentation; we can navigate to the base url of our API and add /api to it, then we should see our first auto-generated documentation page.

Lest add some info to that page, lets document the Greeting Controller

/**
 * Response with a nice "Hello" greeting message
 *
 * @ApiDoc(
 *  section="Greetings",
 *  resource=true,
 *  description="Response with a Hello greeting",
 *  statusCodes={
 *         200="Returned when successful"
 *  },
 *  tags={
 *   "stable" = "#4A7023",
 *  }
 * )
 */

You can see how easy its to document an action, but also grouping it by resources and sections, even farther tagging the end point so the clients can filter for it or be careful in some cases, rise deprecated notices and so on.

Lets see another example on the Customer Controller

/**
 * Response with the customer that has {customer} for id
 *
 * @ApiDoc(
 *  section="Customer",
 *  description="Get a customer",
 *  requirements={
 *      {
 *          "name"="customer",
 *          "dataType"="string",
 *          "requirement"="*",
 *          "description"="customer id"
 *      }
 *  },
 *  statusCodes={
 *         200="Returned when successful"
 *  },
 *  tags={
 *   "stable" = "#4A7023",
 *   "need validations" = "#ff0000"
 *  }
 * )
 */

This one will be the documentation for the get customer action. Even if the bundle its smart enough to collect the action parameters and include it on the documentation, example the {customer} parameter that suppose to be the customer id, the auto-generated page will not include any farther info about it, and remember that documentation should be as expressive as possible, that its why i manually include the specification for the {customer} parameter.

Lastly what about actions that receive data such as posts and puts

/**
 * Create a new customer
 *
 * @ApiDoc(
 *  section="Customer",
 *  description="Create a new Customer",
 *  input="AppBundle\Form\CustomerType",
 *  output="AppBundle\Entity\Customer",
 *  statusCodes={
 *         200="Returned when successful"
 *  },
 *  tags={
 *   "stable" = "#4A7023",
 *   "need validations" = "#ff0000"
 *  },
 *  views = { "premium" }
 * )
 */

This one is the annotation for the new customer action, you can see the input parameter with the form that we will use to capture the data and the output with the suppose response definition of the expected object, that’s great. There is one more option in this annotation and is the views, suppose that only premium clients are allow to create new customers, and lets forget for a moment that we need to validate and secure the action; the bundle allow you through the views option to configure multiple views for each client so you can expose to each client what you need, even if its another grouping option its more powerful.

As explained before this bundle will extract the documentation from the same code we use to deliver the functionalities, inferring as much as possible from the classes names, function names, parameter names and so on.

Conclusion:

Documentation its really important for those clients that suppose to use your API, so thanks to this great bundle we can manage in an easy and fast way deliver it.

With this we manage to cover the 3 first levels of a RESTFul app, we are getting close to the target.

Series:

  1. Motivation
  2. REST Levels 0, 1, 2 ( FOSRestBundle, JMSSerializerBundle )
  3. REST Levels 0, 1, 2 ( FOSUserBundle )
  4. REST Levels 0, 1, 2 ( NelmioApiDocBundle )
  5. REST Levels 3 ( BazingaHateoasBundle )
  6. Security ( FOSOAuthServerBundle )
  7. Security ( Securing the token path )
  8. Security ( Securing the token path – FIXED )
Advertisements

7 Comments

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s