Building a first class REST API with Symfony

Transcript

1. BUILDING FIRST-CLASS REST APIS WITH SYMFONY @MICHAELCULLUMUK SYMFONY LIVE LONDON

   2018

2. BUILDING FIRST-CLASS REST APIS WITH SYMFONY @MICHAELCULLUMUK SYMFONY LIVE LONDON

   2018

3. @MICHAELCULLUMUK ME?

4. MICHAEL CULLUM @MICHAELCULLUMUK

5. @MICHAELCULLUMUK APIS

6. @MICHAELCULLUMUK WHAT IS REST?

7. @MICHAELCULLUMUK REPRESENTATIONAL STATE TRANSFER

8. @MICHAELCULLUMUK REPRESENTATIONAL STATE TRANSFER

9. @MICHAELCULLUMUK ▸ Uniform Interface REPRESENTATIONAL STATE TRANSFER (REST)

10. @MICHAELCULLUMUK ▸ Uniform Interface ▸ Stateless REPRESENTATIONAL STATE TRANSFER (REST)

11. @MICHAELCULLUMUK ▸ Uniform Interface ▸ Stateless ▸ Cacheable REPRESENTATIONAL STATE

    TRANSFER (REST)

12. @MICHAELCULLUMUK ▸ Uniform Interface ▸ Stateless ▸ Cacheable ▸ Client-Server

    REPRESENTATIONAL STATE TRANSFER (REST)

13. @MICHAELCULLUMUK ▸ Uniform Interface ▸ Stateless ▸ Cacheable ▸ Client-Server

    ▸ Layered System REPRESENTATIONAL STATE TRANSFER (REST)

14. @MICHAELCULLUMUK ▸ Uniform Interface ▸ Stateless ▸ Cacheable ▸ Client-Server

    ▸ Layered System ▸ Code on demand (Optional) REPRESENTATIONAL STATE TRANSFER (REST)

15. @MICHAELCULLUMUK SO WHAT?

16. @MICHAELCULLUMUK HTTP RESPONSE CODES

17. @MICHAELCULLUMUK USE HTTP WELL

18. @MICHAELCULLUMUK HTTP VERBS

19. @MICHAELCULLUMUK THE RIGHT HTTP VERBS

20. @MICHAELCULLUMUK HTTP RESPONSE CODES

21. @MICHAELCULLUMUK ▸ 200 - All is right with the world

    ▸ 301 / 302 - Turn around, walk down the road and where you’re looking for is on the right ▸ 400 - You made a mistake ▸ 401 or 403 - You can’t see this, it’s a secret ▸ 404 - I can’t find what you’re asking for ▸ 405 - Fix your HTTP verbs ▸ 500 - Something is wrong with me but I don’t know what. Sorry. BASIC HTTP CODES

22. @MICHAELCULLUMUK ▸ 201 - Created something OK ▸ 202 -

    Accepted but will be properly processed in the background ▸ 422 - Validation Error ▸ 401 - Login! ▸ 403 - You’re not supposed to be here ▸ 410 - This resource did exist, but it’s now been deleted or disabled ▸ 429 - You’ve hit a rate limit, steady on there ▸ 503 - API is not here right now, please try again later BASIC HTTP CODES

23. @MICHAELCULLUMUK RESPONSE CODES $response->setStatusCode(422);

24. @MICHAELCULLUMUK RESPONSE CODES $response->setStatusCode(Response::UNPROCESSABLE_ENTITY);

25. @MICHAELCULLUMUK RESPONSE CODES <?php namespace Symfony\Component\HttpFoundation; class Response { const

    HTTP_OK = 200; const HTTP_CREATED = 201; const HTTP_ACCEPTED = 202; const HTTP_TEMPORARY_REDIRECT = 307; const HTTP_PERMANENTLY_REDIRECT = 308; const HTTP_BAD_REQUEST = 400; const HTTP_UNAUTHORIZED = 401; const HTTP_PAYMENT_REQUIRED = 402; const HTTP_FORBIDDEN = 403; const HTTP_NOT_FOUND = 404; const HTTP_METHOD_NOT_ALLOWED = 405; const HTTP_NOT_ACCEPTABLE = 406; const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407; const HTTP_REQUEST_TIMEOUT = 408; const HTTP_CONFLICT = 409; const HTTP_GONE = 410; const HTTP_LENGTH_REQUIRED = 411; const HTTP_PRECONDITION_FAILED = 412; const HTTP_REQUEST_ENTITY_TOO_LARGE = 413; const HTTP_REQUEST_URI_TOO_LONG = 414; const HTTP_UNSUPPORTED_MEDIA_TYPE = 415; const HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416; const HTTP_EXPECTATION_FAILED = 417; const HTTP_I_AM_A_TEAPOT = 418; const HTTP_UNPROCESSABLE_ENTITY = 422; const HTTP_TOO_MANY_REQUESTS = 429; const HTTP_INTERNAL_SERVER_ERROR = 500; const HTTP_NOT_IMPLEMENTED = 501; const HTTP_BAD_GATEWAY = 502; const HTTP_SERVICE_UNAVAILABLE = 503; const HTTP_GATEWAY_TIMEOUT = 504; }

26. @MICHAELCULLUMUK ERRORS

27. @MICHAELCULLUMUK AN EVENT class ExceptionListener { /** * @param GetResponseForExceptionEvent

    $event */ public function onKernelException(GetResponseForExceptionEvent $event): void { $e = $event->getException(); if ($e instanceof ValidationException) { $response = new ValidationErrorResponse($e->getErrors()); } else { $response = JsonResponse::create( [ 'code' => 'UNKNOWN_ERROR', 'message' => $e->getMessage(), ], Response::HTTP_INTERNAL_SERVER_ERROR ); } $event->setResponse($response); } }

28. @MICHAELCULLUMUK EXCEPTION CONTROLLER OVERRIDE <?php declare(strict_types=1); namespace SamKnows\Common\Controller; class ExceptionController

    extends DefaultExceptionController { public function showAction(Request $request, FlattenException $exception, DebugLoggerInterface $logger = null): Response }

29. @MICHAELCULLUMUK EXCEPTION CONTROLLER OVERRIDE public function showAction(Request $request, FlattenException $exception,

    DebugLoggerInterface $logger = null) { $code = $exception->getStatusCode(); $body = $this->getError($exception, $this->debug); $response = new JsonResponse( $body, $code ); $response->headers->set('Content-Type', 'application/json; charset=UTF-8'); return $response; }

30. @MICHAELCULLUMUK EXCEPTION CONTROLLER OVERRIDE public function getError(FlattenException $exception) { $error

    = []; $mapping = $this->errorMap[$exception->getClass()]; $error['code'] = $mapping[‘code'] ?? 'UNKNOWN_ERROR', $error['message'] = $mapping[‘message'] ?? 'Unknown error'; if ($exception->getClass() === ValidationException::class) { $error['errors'] = $exception->getErrors(); } if ($this->twig->isDebug()) { $error['debug'] = sprintf( '%s in file %s amd line %d', $exception->getMessage(), $exception->getFile(), $exception->getLine() ); } return $error; } private $errorMap = [ AccessDeniedException::class => [ 'code' => 'ACCESS_DENIED', 'message' => 'Access Denied', ], ValidationException::class => [ 'code' => 'VALIDATION_FAIL', 'message' => 'Validation failed', ], ];

31. @MICHAELCULLUMUK DTO ALL THE THINGS

32. @MICHAELCULLUMUK PARAM CONVERTER IS YOUR FRIEND

33. @MICHAELCULLUMUK PARAM CONVERTOR + DTO public function postAddressesAction(AddressCreateDTO $addressCreateDTO): Response

    { // ... $address = $this->entityPersister->mapAndPersist($addressCreateDTO, new Address()); // ... }

34. @MICHAELCULLUMUK DTO PARAMETER CONVERTOR class DataTransferObjectConverter implements ParamConverterInterface { //

    Constructor etc. ... public function apply(Request $request, ParamConverter $configuration) { $data = $request->get('content'); $class = $configuration->getClass(); $dto = $this->serializer->denormalize($data, $class); if ($request->files->count() > 0) { $dto = $this->serializer->denormalize($request->files->all(), $class, [ 'object_to_populate' => $dto, ]); } $request->attributes->set($configuration->getName(), $dto); return true; } // supports() etc. ... }

35. @MICHAELCULLUMUK VALIDATION

36. @MICHAELCULLUMUK EXCEPTIONS!

37. @MICHAELCULLUMUK REMOVE CONTROL FROM CONTROLLERS

38. @MICHAELCULLUMUK CONTROLLER public function postAddressesAction(AddressCreateDTO $addressCreateDTO): Response { try {

    $address = $this->entityPersister->mapAndPersist($addressCreateDTO); } catch (ValidationException $exception) { return new ValidationErrorResponse($exception); } return $this->created( 'addresses_item', [ 'id' => $address->getId(), ] ); }

39. @MICHAELCULLUMUK FORMATTING YOUR OUTPUT

40. @MICHAELCULLUMUK SYMFONY SERIALIZER COMPONENT

41. @MICHAELCULLUMUK TRANFORMERS

42. @MICHAELCULLUMUK FRACTAL

43. @MICHAELCULLUMUK FRACTAL TRANSFORMER class AddressTransformer extends TransformerAbstract { protected $availableIncludes

    = [ 'account', ]; public function transform(Address $address) { return [ 'id' => $address->getId(), 'address_line_1' => $address->getAddressLine1(), 'address_line_2' => $address->getAddressLine2(), 'address_line_3' => $address->getAddressLine3(), 'county' => $address->getCounty(), 'city' => $address->getCity(), 'postcode' => $address->getPostcode(), 'country' => $address->getCountry(), 'updated_at' => $address->getUpdatedAt() ? $address->getUpdatedAt()->getTimestamp() : null, ]; } }

44. @MICHAELCULLUMUK FRACTAL TRANSFORMER // Create your resource, or collection of

    resources $resource = new Fractal\Resource\Item($book, new BookTransformer); $resource = new Fractal\Resource\Collection($books, new BookTransformer); // Turn that into a structured array (handy for XML views or auto-YAML converting) $array = $fractal->createData($resource)->toArray(); // Turn all of that into a JSON string $fractal->createData($resource)->toJson();

45. @MICHAELCULLUMUK PAGINATION AND LINKS

46. @MICHAELCULLUMUK NOBODY LIKES PAGINATION

47. @MICHAELCULLUMUK ▸ Do it ▸ Link to the next and

    previous pages ▸ Detail the current page number ▸ Detail the total number of pages REST PAGINATION TODO LIST

48. @MICHAELCULLUMUK DISABLING A TOTAL CAN MAKE THINGS QUICKER

49. @MICHAELCULLUMUK DOCTRINE PAGINATOR

50. @MICHAELCULLUMUK PAGERFANTA

51. @MICHAELCULLUMUK FRACTAL INTEGRATION

52. @MICHAELCULLUMUK PAGINATED OR NOT public function getUsersAction(Request $request, UserFilters $filters):

    Response { // ... $paginator = $this->grantRepository->findAllPaginated($filters); return $this->success($paginator, UserTransformer::class, $request->query->get('include')); } public function getUsersAction(Request $request, GrantFilters $filters): Response { // ... $users = $this->grantRepository->findAll($filters); return $this->success($users, UserTransformer::class, $request->query->get('include')); }

53. @MICHAELCULLUMUK GETTING IT TO YOUR REPOSITORY

54. @MICHAELCULLUMUK PUT IT IN AN OBJECT public function getUsersAction(Request $request,

    UserFilters $filters): Response { // ... $paginator = $this->grantRepository->findAllPaginated($filters); return $this->success($paginator, UserTransformer::class, $request->query->get('include')); }

55. @MICHAELCULLUMUK SORTS AND FILTERS

56. @MICHAELCULLUMUK THERE’S AN OBJECT FOR THAT

57. @MICHAELCULLUMUK QUERY STRING [GET] /users?page=1&per_page=20&sorts=-id&include=groups%2Caddress&email=michael Pagination Sorting Includes Filters

58. @MICHAELCULLUMUK CONTROLLER public function getAddressesAction(Request $request, AddressFilters $filters): Response

59. @MICHAELCULLUMUK FILTER CLASS class AddressFilters { use PaginationFilterTrait; use SortingFiltersTrait;

    public function getUser() { return $this->user; } /** * @param int $user */ public function setUser($user) { $this->user = $user; } } trait PaginationFilterTrait { private $page = 1; private $perPage = 10; // ... Getters and setters... } trait SortingFiltersTrait { private $sorts = []; // ... Getters and setters ... }

60. @MICHAELCULLUMUK REPOSITORY public function findAllPaginated(AddressFilters $addressFilters) { $queryBuilder = $this->createQueryBuilder('address');

    $this->addFilter($queryBuilder, 'user', $addressFilters->getUser()); $this->addSorts($queryBuilder, $filter->getSorts()); return $this->createPaginator($queryBuilder, $addressFilters->getPage(), $addressFilters->getPerPage()); }

61. @MICHAELCULLUMUK ADD SORTS AND ADD FILTERS METHODS protected function addSorts(QueryBuilder

    $queryBuilder, array $sorts): void { if (count($sorts) > 0) { foreach ($sorts as $sort) { $field = $this->getFieldFromMap($sort[0]); if ($field) { $queryBuilder->addOrderBy($field, $sort[1]); } } } } protected function addFilter(QueryBuilder $queryBuilder, $name, $value, string $parameter = null): void { $field = $this->getFieldFromMap($name); if ($value === null || $value == '') { return; } if ($parameter === null) { $parameter = $name; } if ($field) { $queryBuilder->andWhere(sprintf('%s = :%s', $field, $parameter)); $queryBuilder->setParameter($parameter, $value); } }

62. @MICHAELCULLUMUK TOOLS

63. @MICHAELCULLUMUK API PLATFORM

64. @MICHAELCULLUMUK API PLATFORM composer require api

65. @MICHAELCULLUMUK DEMO

66. @MICHAELCULLUMUK FOS REST BUNDLE

67. @MICHAELCULLUMUK EXCEPTION CONTROLLER fos_rest: exception: codes: 'Symfony\Component\Routing\Exception\ResourceNotFoundException': 404 'Doctrine\ORM\OptimisticLockException': HTTP_CONFLICT

    messages: 'Acme\HelloBundle\Exception\MyExceptionWithASafeMessage': true

68. @MICHAELCULLUMUK VIEW LAYER public function getUsersAction() { $data = ...;

    // get data, in this case list of users. $view = $this->view($data, 200) ->setTemplate("MyBundle:Users:getUsers.html.twig") ->setTemplateVar('users') ; return $this->handleView($view); }

69. @MICHAELCULLUMUK AUTOMATIC ROUTING # routes.yml users: type: rest host: m.example.com

    resource: Acme\Controller\UsersController <?php namespace AppBundle\Controller; class UsersController { public function getUsersAction() {} // "get_users" [GET] /users public function postUsersAction() {} // "post_users" [POST] /users public function putUserAction($slug) {} // "put_user" [PUT] /users/{slug} public function patchUserAction($slug) {} // "patch_user" [PATCH] /users/{slug} public function deleteUserAction($slug) {} // "delete_user" [DELETE] /users/{slug} }

70. @MICHAELCULLUMUK RECAP

71. @MICHAELCULLUMUK ▸ Principles of REST RECAP

72. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well RECAP

73. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    Error handling RECAP

74. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter RECAP

75. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter ▸ Validation RECAP

76. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter ▸ Validation ▸ Formatting output RECAP

77. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter ▸ Validation ▸ Formatting output ▸ Pagination RECAP

78. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter ▸ Validation ▸ Formatting output ▸ Pagination RECAP ▸ Sorts & Filters

79. @MICHAELCULLUMUK ▸ Principles of REST ▸ Using HTTP well ▸

    DTOs and the Param Converter ▸ Validation ▸ Formatting output ▸ Pagination RECAP ▸ Sorts & Filters ▸ Tools ▸ API Platform ▸ FOS Rest Bundle

80. THANKS @MICHAELCULLUMUK

81. @MICHAELCULLUMUK ANY QUESTIONS?

82. BUILDING FIRST-CLASS REST APIS WITH SYMFONY @MICHAELCULLUMUK SYMFONY LIVE LONDON

    2018