Service approach for development REST API in Symfony2

Service approach for
development Rest API in
Symfony2
Aleksey Kryvtsov @ Web-developer at CPCS
alkryvtsov@gmail.com

Development Rest API in Symfony2
2

● Interface as contracts.
● Thin Controller, Fat Service.
● The Content Negotiation in the HTTP and REST.
● Form as API interface.
Rules
3

● FOSRestBundle
● JMSSerializerBundle
● NelmioApiDocBundle
List of bundles
// app/AppKernel.php
$bundles = [
//...
new FOSRestBundleFOSRestBundle(),
new JMSSerializerBundleJMSSerializerBundle(),
new
NelmioApiDocBundleNelmioApiDocBundle(),
4

/api/v1/{_lang}/pages/{id}.{_format}
/api/v1/en/pages/{id}.json
Will return a json file
/api/v1/en/pages/{id}.xml
Will return a xml file
/api/v1/en/pages/{id} and /api/v1/en/pages/{id}.html
Will return the web page file
Format of routing
5

# /app/config/routing.yml
acme_api_blog:
type: rest
prefix: /api/v1/{_lang}
resource:
"@AcmeBlogBundle/Resources/config/routes.yml"
Adding the routes
6

# /src/Acme/BlogBundle/Resources/config/routes.yml
acme_api_blog_page:
resource:
"AcmeBlogBundleControllerPageController"
name_prefix: api_v1_ # naming collision
Create a route file into the bundle
# php app/console route:debug | grep api_v1_
7

# /src/Acme/BlogBundle/Controller/PageController.php
namespace AcmeBlogBundleController;
use FOSRestBundleControllerFOSRestController as Rest;
class PageController extends Rest {
// another methods POST, PUT, DELETE and etc...
/* @annotations */
public function getPageAction ($id) {
return $this->get('acme_blog.blog_post.handler')->get($id);
}
}
Controller: PageController::getPageAction ()
8

use FOSRestBundleControllerAnnotations as FOSRest;
/**
* Get single Page
* @FOSRestGet("/pages/{id}", requirements={"id" = "d+"}, name="get_page")
* @FOSRestView(serializerGroups={"page"})
*
* @ApiDoc(/* documentation */)
*
* @param int $id The page id
*
* @return array
* @throws NotFoundHttpException when page not exist or not found
*/
public function getPageAction ($id) {}
Controller: PageController::getPageAction ()
9

# /src/Acme/BlogBundle/Entity/Page.php
namespace AcmeBlogBundleEntity;
class Page implements PageInterface {
// fields, getters and setters
}
Interface as contract
# /src/Acme/BlogBundle/Model/PageInterface.php
namespace AcmeBlogBundleModel;
interface PageInterface {
}
10

Handler configuration. Part I
# /src/Acme/BlogBundle/Resources/config/handlers.yml
services:
1 acme_blog.page.entity:
class: AcmeBlogBundleEntityPage
2 acme_blog.blog_post.handler:
class: AcmeBlogBundleHandlerPageHandler
arguments:
3 - @doctrine.orm.entity_manager
4 - @acme_blog.page.entity
11

HandlerInterface: PageHandlerInterface::get()
# /src/Acme/BlogBundle/Handler/PageHandlerInterface.php
namespace AcmeBlogBundleHandler;
use AcmeBlogBundleModelPageInterface;
interface PageHandlerInterface {
/**
* Gets a page by id
*
* @api
* @param integer $id
*
* @return PageInterface
*/
public function get ($id);
}
12

Handler: PageHandler::__construct()
# /src/Acme/BlogBundle/Handler/PageHandler.php
use DoctrineORMEntityManager;
class PageHandler implements PageHandlerInterface {
// another methods
/**
* @return void
*/
public function __construct(
EntityManager $entityManager,
PageInterface $pageEntity
) // continue...
13

// another methods
/* public function __construct (...) */ {
1 $this->entityManager = $entityManager;
2 $this->pageEntity = $pageEntity;
3 $this->repository = $entityManager->getRepository(get_class($pageEntity));
}
}
14

Handler: PageHandler::get()
/**
* {@inheritdoc}
*/
public function get ($id) {
return $this->repository->find($id);
}
}
16

Controller: PageController::getAllPagesAction()
17
URL: ~/pages

18
Diagram: getAction, getAllAction

use SymfonyComponentHttpFoundationRequest;
// another methods
/* @annotations -> URL: ~/pages */
public function postPageAction(Request $request) {
return $this->get('acme_blog.blog_post.handler')
->post($request->request->all());
}
}
Controller: PageController::postPageAction ()
19

HandlerInterface: PageHandlerInterface::post()
/**
* Creates a new page
*
* @api
* @param array $parameters
* @param array $options
*
*/
public function post(array $parameters = [], array $options = []);
}
20

Handler: PageHandler::post()
/* {@inheritdoc} */
public function post (
array $parameters = [],
array $options = []
) {
return $this->processForm(
$this->pageClass,
$parameters,
$options,
“POST”
);
}
21

Handler configuration. Part II
# /src/Acme/BlogBundle/Resources/config/handlers.yml
services:
// ...
acme_blog.page.form_type:
class: AcmeBlogBundleFormTypePageFormType
acme_blog.blog_post.handler:
class: AcmeBlogBundleHandlerPageHandler
arguments:
- @doctrine.orm.entity_manager
- @acme_blog.page.entity
- @form.factory
- @acme_blog.page.form_type
22

use SymfonyComponentFormFormFactoryInterface;
use use SymfonyComponentFormFormTypeInterface;
/**
* @return void
*/
public function __construct (
//...
FormFactoryInterface $formFactory,
FormTypeInterface $formType
) {
// ...
$this->formFactory = $formFactory;
$this->formType = $formType;
} 23

HandlerInterface: PageHandlerInterface::processForm()
/**
* Processes the form
*
* @api
* @param PageInterface $page
* @param array $parameters
* @param array $options
* @param string $method
*
*/
private function processForm(PageInterface $page, array $parameters = [], array $options = [],
$method
)
} 24

Handler: PageHandler::processForm()
protected function processForm (/*...*/) {
1 $form = $this->formFactory->create($this->formType, $page, $options);
2 $form->submit($parameters, 'PATCH' !== $method);
3 if ($form->isValid()) {
4 $this->entityManager->persist($page);
5 $this->entityManager->flush($page);
6 return $page;
}
7 // throw new InvalidFormException(/*...*/)
}
25

Controller: PageController::[patch|put]PageAction()
26
URL: ~/pages/{id}

Handler: PageHandler::patch()
// another methods
public function patch(array $parameters = [], array $options = []) {
1 $page = $this->get($parameters[‘id’]);
2 return $this->processForm(
$page,
$parameters,
$options,
“PATCH”
);
}
27

Handler: PageHandler::put()
// another methods
public function put(array $parameters = [], array $options = []) {
1 $page = $this->get($parameters[‘id’]);
2 return $this->processForm(
$page,
$parameters,
$options,
“PUT”
);
}
28

29
Diagram: postAction, putAction, patchAction

// another methods
/* @annotations -> URL: ~/pages/{id} */
public function deletePageAction($id) {
return $this->get('acme_blog.blog_post.handler')->delete($id);
}
}
Controller: PageController::deletePageAction()
30

HandlerInterface: PageHandlerInterface::delete()
/**
* Returns the result of removal
*
* @api
* @param integer $id
*
* @return string
*/
public function delete($id);
}
31

Handler: PageHandler::delete()
/**
* {@inheritdoc}
*/
public function delete ($id) {
1 $page = $this->get($id);
2 $this->entityManager->remove($page);
3 $this->entityManager->flush();
}
}
32

1. # app/config/routing.yml
NelmioApiDocBundle:
resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
prefix: /api/doc
Documentation: ApiDoc
35
2. # /src/Acme/BlogBundle/Controller/PageController.php
/**
* @ApiDoc(
* description = "Creates a new page from the submitted data.",
* input = "AcmeBlogBundleFormPageType",
* output = "AcmeBlogBundleEntityPage",
* statusCodes = {
* 200 = "Returned when successful",
* 400 = "Returned when the form has errors"
* }
* )
*/

JMSSerializer
37
# /src/Acme/BlogBundle/Entity/Page.php
use DoctrineORMMapping as ORM;
use JMSSerializerAnnotation as JMS;
/**
* @ORMEntity
* @JMSExclusionPolicy("all")
*/
class Page {
/**
* @JMSExpose
* @JMSType("AnotherClass")
* @JMSGroups({"page", "details"})
* @ORMManyToOne(targetEntity="AnotherClass")
* @ORMJoinColumn(name="column", referencedColumnName="id")
*/
protected $field;
{
"id": 1,
"field": AnotherClass,
"another": "anotherType"
}

JMSSerializer: Annotations
38
● @ExclusionPolicy
● @Exclude
● @Expose
● @SerializedName
● @Since
● @Until
● @Groups
● @MaxDepth
● @AccessType
● @Accessor
● @ReadOnly
● @PreSerialize
● @PostSerialize
● @PostDeserialize
● @HandlerCallback
● @Discriminator
● @Type
● @XmlRoot
● @XmlAttribute
● @XmlValue

References
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
Best Practices for Designing a Pragmatic RESTful API
http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way
REST APIs with Symfony2: The Right Way
https://www.youtube.com/watch?v=Kkby5fG89K0
Lukas Kahwe Smith (Symfony Camp)
http://welcometothebundle.com/symfony2-rest-api-the-best-2013-way
Symfony2 REST API: the best way
https://github.com/liuggio/symfony2-rest-api-the-best-2013-way
The github repository
39

Thank you
Questions ?
Aleksey Kryvtsov alkryvtsov@gmail.com
40

Service approach for development REST API in Symfony2

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to Service approach for development REST API in Symfony2 (20)

More from Sumy PHP User Grpoup (6)

Recently uploaded (20)

Service approach for development REST API in Symfony2