Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The quickest way to stable API in Laravel

The quickest way to stable API in Laravel

Builiding API using great combination of tools and workflows how we can vastly speedup and improve our API development, without compromising stability and testability.

Ffdbe721956f8197910842756fcfb44a?s=128

Milan Popović

March 23, 2016
Tweet

More Decks by Milan Popović

Other Decks in Programming

Transcript

  1. THE QUICKEST WAY TO STABLE API USING LARAVEL FRAMEWORK Presented

    by / Milan Popović @komita1981
  2. ME PHP developer Work for Navus Consulting Gmbh I like

    to learn and share knowledge Active member of PHP Srbija
  3. Why Laravel? Enables rapid development Stable and well tested Community

    support Documentation Learning resources Easy to recruit developers LTS
  4. Why Laravel for quick API development? DB Migration DB seeding

    Model factory Form request Testing 3rd Party Packages
  5. DB MIGRATION Version control for you DB schema Laravel Schema

    facade provides database agnostic support for creating and manipulating tables / / C r e a t e n e w m i g r a t i o n p h p a r t i s a n m a k e : m i g r a t i o n c r e a t e _ u s e r s _ t a b l e / / R u n m i g r a t i o n p h p a r t i s a n m i g r a t e / / R o l l b a c k m i g r a t i o n p h p a r t i s a n m i g r a t e
  6. DB SEED Sample/Test data for your DB / / C

    r e a t e n e w s e e d e r p h p a r t i s a n m a k e : s e e d e r U s e r s T a b l e S e e d e r / / R u n s e e d e r s p h p a r t i s a n d b : s e e d / / R u n s e e d e r s v 2 p h p a r t i s a n m i g r a t e - - s e e d / / R u n s i n g l e s e e d e r p h p a r t i s a n d b : s e e d - - c l a s s = U s e r s T a b l e S e e d e r
  7. MODEL FACTORY Default model attributes Uses Faker for generating values

    $ f a c t o r y - > d e f i n e ( A p p \ U s e r : : c l a s s , f u n c t i o n ( F a k e r \ G e n e r a t o r $ f a k e r ) { r e t u r n [ ' n a m e ' = > $ f a k e r - > n a m e , ' e m a i l ' = > $ f a k e r - > e m a i l , ' p a s s w o r d ' = > b c r y p t ( s t r _ r a n d o m ( 1 0 ) ) , ' r e m e m b e r _ t o k e n ' = > s t r _ r a n d o m ( 1 0 ) , ] ; } ) ;
  8. Multiple Factory Types - multiple factories for the same Eloquent

    model class $ f a c t o r y - > d e f i n e A s ( A p p \ U s e r : : c l a s s , ' a d m i n ' , f u n c t i o n ( $ f a k e r ) u s e ( $ f a c t o r y $ u s e r = $ f a c t o r y - > r a w ( A p p \ U s e r : : c l a s s ) ; r e t u r n a r r a y _ m e r g e ( $ u s e r , [ ' a d m i n ' = > t r u e ] ) ; } ) ;
  9. Attach relationships $ f a c t o r y

    - > d e f i n e ( A p p \ P o s t : : c l a s s , f u n c t i o n ( $ f a k e r ) { r e t u r n [ ' t i t l e ' = > $ f a k e r - > t i t l e , ' c o n t e n t ' = > $ f a k e r - > p a r a g r a p h , ' u s e r _ i d ' = > f u n c t i o n ( ) { r e t u r n f a c t o r y ( A p p \ U s e r : : c l a s s ) - > c r e a t e ( ) - > i d ; } , ' u s e r _ t y p e ' = > f u n c t i o n ( a r r a y $ p o s t ) { r e t u r n A p p \ U s e r : : f i n d ( $ p o s t [ ' u s e r _ i d ' ] ) - > t y p e ; } ] ; } ) ;
  10. Using factories / / C r e a t e

    t h r e e A p p \ U s e r i n s t a n c e s . . . $ u s e r s = f a c t o r y ( A p p \ U s e r : : c l a s s , 3 ) - > m a k e ( ) ; / / C r e a t e t h r e e A p p \ U s e r " a d m i n " i n s t a n c e s . . . $ u s e r s = f a c t o r y ( A p p \ U s e r : : c l a s s , ' a d m i n ' , 3 ) - > m a k e ( ) ; / / C r e a t e A p p \ U s e r u s e r w i t h g i v e n n a m e . . . $ u s e r = f a c t o r y ( A p p \ U s e r : : c l a s s ) - > m a k e ( [ ' n a m e ' = > ' A b i g a i l ' , ] ) ; / / P e r s i s t i n g F a c t o r y M o d e l s $ u s e r = f a c t o r y ( A p p \ U s e r : : c l a s s ) - > c r e a t e ( ) ;
  11. FORM REQUESTS Special class for validating request params and authorizing

    Each class has rules() (returns array) and authorize() (returns boolean) methods Type Hinting in Controller methods
  12. p u b l i c f u n c

    t i o n r u l e s ( ) { r e t u r n [ ' t i t l e ' = > ' r e q u i r e d | u n i q u e : p o s t s | m a x : 2 5 5 ' , ' b o d y ' = > ' r e q u i r e d ' , ] ; } p u b l i c f u n c t i o n a u t h o r i z e ( ) { $ c o m m e n t I d = $ t h i s - > r o u t e ( ' c o m m e n t ' ) ; r e t u r n C o m m e n t : : w h e r e ( ' i d ' , $ c o m m e n t I d ) - > w h e r e ( ' u s e r _ i d ' , A u t h : : i d ( ) ) - > e x i s t s ( ) ; }
  13. TESTING PHPUnit is included out of the box Laravel is

    built with testing in mind It's also ships with convenient helper methods Uses Mockery as mock object framework
  14. WORKING WITH DATABASE Using Migrations - DatabaseMigrations trait DatabaseTransactions -

    DatabaseTransactions trait Model Factories
  15. WORKING WITH DATABASE SeeInDatabase helper seeInDatabase($table, array $data, $connection =

    null) NotSeeInDatabase helper notSeeInDatabase($table, array $data, $connection = null) Seed (seed($class = 'DatabaseSeeder')
  16. CREATING HTTP REQUEST / / M a i n m

    e t h o d p u b l i c f u n c t i o n c a l l ( $ m e t h o d , $ u r i , $ p a r a m e t e r s = [ ] , $ c o o k i e s = [ ] , $ f i l e s = / / T h e r e a r e a l s o m e t h o d s f o r o t h e r h t t p v e r b s p u b l i c f u n c t i o n p o s t ( $ u r i , a r r a y $ d a t a = [ ] , a r r a y $ h e a d e r s = [ ] ) / / V i s i t t h e g i v e n U R I w i t h a J S O N r e q u e s t . p u b l i c f u n c t i o n j s o n ( $ m e t h o d , $ u r i , a r r a y $ d a t a = [ ] , a r r a y $ h e a d e r s = [ ] ) { / / r e m o v e d c o d e f r o m o r i g i n a l m e t h o d $ c o n t e n t = j s o n _ e n c o d e ( $ d a t a ) ; $ h e a d e r s = a r r a y _ m e r g e ( [ ' C O N T E N T _ L E N G T H ' = > m b _ s t r l e n ( $ c o n t e n t , ' 8 b i t ' ) , ' C O N T E N T _ T Y P E ' = > ' a p p l i c a t i o n / j s o n ' , ' A c c e p t ' = > ' a p p l i c a t i o n / j s o n ' , ] , $ h e a d e r s ) ;
  17. PHPUNIT ASSERTIONS FOR STATUS CODE AND HEADERS assertResponseOk() assertResponseStatus($code) seeStatusCode($status)

    seeHeader($headerName, $value)
  18. PHPUNIT ASSERTIONS FOR JSON seeJsonEquals($data) seeJsonStructure($structure, $responseData) seeJsonContains($data, $negate) seeJsonSubset($data)

  19. PACKAGES & TOOLS Dingo API Dredd Repositories CORS

  20. DINGO API " r e q u i r e

    " : { " d i n g o / a p i " : " 1 . 0 . * @ d e v " } Provides set of tools to easily and quickly build your own API Requires Laravel 5.1+ or Lumen 5.1+ and PHP 5.5.9+
  21. CONFIGURATION Much of the package comes preconfigured Use your .env

    file to configure most of the package Finer tuning of the package will require publishing the configuration file
  22. Configure: Name Default Version Authentication Provider Throttling / Rate Limiting

    (Disabled by default) Response Transformer (Fractal is the default) Response Format (JSON and a JSON response format is registered by default) Error Format
  23. CREATING API ENDPOINTS / / T o a v o

    i d c o m p l i c a t i o n s w i t h y o u r m a i n a p p l i c a t i o n r o u t e s t h i s p a c k a g e u t i l $ a p i = a p p ( ' D i n g o \ A p i \ R o u t i n g \ R o u t e r ' ) ; $ a p i - > v e r s i o n ( ' v 1 ' , f u n c t i o n ( $ a p i ) { $ a p i - > p o s t ( ' r e g i s t e r ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ R e g i s t e r C o n t r o l l e r $ a p i - > p o s t ( ' l o g i n ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ L o g i n C o n t r o l l e r @ l o g i n $ a p i - > g e t ( ' b l o c k s ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ B l o c k s C o n t r o l l e r @ g e t A $ a p i - > g e t ( ' b l o c k s / { i d } ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ B l o c k s C o n t r o l l e r $ a p i - > p o s t ( ' b l o c k s ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ B l o c k s C o n t r o l l e r @ c r e $ a p i - > p u t ( ' b l o c k s / { i d } ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ B l o c k s C o n t r o l l e r $ a p i - > d e l e t e ( ' b l o c k s / { i d } ' , ' S a m p l e A p i \ H t t p \ C o n t r o l l e r s \ B l o c k s C o n t r o l } ) ;
  24. RESPONSES There's a number of different ways to return responses

    Use Response Builder Provides a fluent interface to easily build a more customizable response Generally used in conjunction with transformers. Use the Dingo\Api\Routing\Helpers trait
  25. u s e D i n g o \ A

    p i \ R o u t i n g \ H e l p e r s ; u s e I l l u m i n a t e \ R o u t i n g \ C o n t r o l l e r ; c l a s s A p i C o n t r o l l e r e x t e n d s C o n t r o l l e r { u s e H e l p e r s ; }
  26. RESPONDING WITH AN ARRAY p u b l i c

    f u n c t i o n s h o w ( $ i d ) { $ b l o c k = $ t h i s - > b l o c k - > f i n d ( $ i d ) ; r e t u r n $ t h i s - > r e s p o n s e - > a r r a y ( $ b l o c k - > t o A r r a y ( ) ) ; }
  27. RESPONDING WITH A SINGLE ITEM p u b l i

    c f u n c t i o n s h o w ( $ i d ) { $ b l o c k = $ t h i s - > b l o c k - > f i n d ( $ i d ) ; r e t u r n $ t h i s - > r e s p o n s e - > i t e m ( $ b l o c k , n e w B l o c k T r a n s f o r m e r ) ; }
  28. RESPONDING WITH A COLLECTION OF ITEMS p u b l

    i c f u n c t i o n s h o w ( $ i d ) { $ b l o c k s = $ t h i s - > b l o c k - > f i n d ( $ i d ) ; r e t u r n $ t h i s - > r e s p o n s e - > c o l l e c t i o n ( $ b l o c k s , n e w B l o c k T r a n s f o r m e r ) ; }
  29. RESPONDING WITH PAGINATED ITEMS p u b l i c

    f u n c t i o n s h o w ( $ i d ) { $ b l o c k s = $ t h i s - > b l o c k - > f i n d ( $ i d ) ; r e t u r n $ t h i s - > r e s p o n s e - > p a g i n a t i o n ( $ b l o c k s , n e w B l o c k T r a n s f o r m e r ) ; }
  30. OTHER RESPONSES / / R e s p o n

    d i n g W i t h N o C o n t e n t r e t u r n $ t h i s - > r e s p o n s e - > n o C o n t e n t ( ) ; / / R e s p o n d i n g W i t h C r e a t e d R e s p o n s e r e t u r n $ t h i s - > r e s p o n s e - > c r e a t e d ( ) ; / / A g e n e r i c e r r o r w i t h c u s t o m m e s s a g e a n d s t a t u s c o d e . r e t u r n $ t h i s - > r e s p o n s e - > e r r o r ( ' T h i s i s a n e r r o r . ' , 4 0 4 ) ; / / A n o t f o u n d e r r o r w i t h a n o p t i o n a l m e s s a g e a s t h e f i r s t p a r a m e t e r . r e t u r n $ t h i s - > r e s p o n s e - > e r r o r N o t F o u n d ( ) ; / / T h e r e a r e a l s o e r r o r B a d R e q u e s t , e r r o r F o r b i d d e n , e r r o r I n t e r n a l , e r r o r U n a u t h
  31. Adding Additional Headers r e t u r n $

    t h i s - > r e s p o n s e - > i t e m ( $ u s e r , n e w U s e r T r a n s f o r m e r ) - > w i t h H e a d e r ( ' X - F o o ' Adding Meta Data r e t u r n $ t h i s - > r e s p o n s e - > i t e m ( $ u s e r , n e w U s e r T r a n s f o r m e r ) - > a d d M e t a ( ' f o o ' / / s e t a n a r r a y o f m e t a d a t a i n s t e a d o f c h a i n i n g m u l t i p l e m e t h o d c a l l s r e t u r n $ t h i s - > r e s p o n s e - > i t e m ( $ u s e r , n e w U s e r T r a n s f o r m e r ) - > s e t M e t a ( $ m e t a Setting Response Status Code r e t u r n $ t h i s - > r e s p o n s e - > i t e m ( $ u s e r , n e w U s e r T r a n s f o r m e r ) - > s e t S t a t u s C o d e
  32. TRANSFORMERS Easily and consistently transform objects into an array Type-cast

    integers and booleans, include pagination results, and nest relationships Fractal is the default transformation layer used by Dingo
  33. p u b l i c f u n c

    t i o n _ _ c o n s t r u c t ( ) { $ t h i s - > a v a i l a b l e I n c l u d e s = [ ' p r e s e n t a t i o n s ' , ' b l o c k _ s e t t i n g s ' , ] ; $ t h i s - > d e f a u l t I n c l u d e s = [ ' b l o c k _ s e t t i n g s ' , ] ; } p u b l i c f u n c t i o n t r a n s f o r m ( B l o c k $ b l o c k ) { r e t u r n [ ' i d ' = > ( i n t ) $ b l o c k - > i d , ' n a m e ' = > $ b l o c k - > n a m e ,
  34. None
  35. None
  36. FORM REQUEST END ERROR RESPONSES Extend the base API form

    request class Implement your own class Dingo\Api\Exception\ValidationHttpException should be thrown
  37. AUTHENTICATION HTTP Basic (Dingo\Api\Auth\Provider\Basic) JSON Web Tokens (Dingo\Api\Auth\Provider\JWT) OAuth 2.0

    (Dingo\Api\Auth\Provider\OAuth2) Custom Authentication Providers
  38. DOCUMENTATION API Blueprint Documentation Annotate API controllers Generate documentation using

    the Artisan command But...
  39. DREDD — HTTP API TESTING FRAMEWORK

  40. “ Dredd is a language-agnostic command-line tool for validating API

    documentation written in API Blueprint format against its backend implementation. ” Dredd reads your API description Validates whether API replies with expected responses Continuous Integration Support Hooks — a glue code for each test setup and teardown Use of Gavel.js library Do not install dredd manually on Homestead - use a er.sh
  41. HEADERS EXPECTATIONS All headers given in example must be present

    in the response Only values of headers significant for content negotiation are validated All other headers values can differ
  42. BODY EXPECTATIONS All JSON keys on any level given in

    the example must be present in the response JSON Response JSON values must be of the same JSON primitive type All JSON values can differ Arrays can have additional items, type or structure is not validated. Plain text must match perfectly
  43. PHP Dredd hook handler Provides a bridge between the Dredd

    API Testing Framework and PHP environment " r e q u i r e - d e v " : { " d d e l n a n o / d r e d d - h o o k s - p h p " : " ~ 1 . 0 . 0 " , }
  44. HOOKS USAGE Loading db fixtures Cleanup a er test step

    or steps Handling authentication and sessions Passing data between transactions (saving state from responses to stash) Modifying request generated from blueprint Changing generated expectations Setting custom expectations Debugging via logging stuff
  45. HOOKS TYPE beforeEach a erEach beforeAll a erAll before a

    er beforeEachValidationHooks a erEachValidationHooks
  46. r e q u i r e _ _ D

    I R _ _ . ' / . . / . . / . . / v e n d o r / a u t o l o a d . p h p ' ; $ a p p = r e q u i r e _ _ D I R _ _ . ' / . . / . . / . . / b o o t s t r a p / a p p . p h p ' ; $ a p p - > m a k e ( \ I l l u m i n a t e \ C o n t r a c t s \ C o n s o l e \ K e r n e l : : c l a s s ) - > b o o t s t r a p ( ) ; A r t i s a n : : c a l l ( ' m i g r a t e ' ) ; $ u s e r = f a c t o r y ( \ E m a t e r i a l s \ A p i \ M o d e l s \ U s e r : : c l a s s ) - > c r e a t e ( [ ' e m a i l ' = > ' k n o w n u s e r @ e x a m p l e . d e v ' ] ) ; H o o k s : : b e f o r e E a c h ( f u n c t i o n ( & $ t r a n s a c t i o n ) u s e ( $ a p p ) { $ a p p - > m a k e ( ' d b ' ) - > b e g i n T r a n s a c t i o n ( ) ; } ) ; H o o k s : : a f t e r E a c h ( f u n c t i o n ( & $ t r a n s a c t i o n ) u s e ( $ a p p ) {
  47. RUN DREDD d r e d d d o c

    u m e n t a t i o n . a p i b h t t p : / / l o c a l h o s t : 8 0 0 1 - - s e r v e r " p h p - S 0 . 0 . 0 . 0 : 8 0 0 1 - t p u b l i c / " - - l a n g u a g e v e n d o r / b i n / d r e d d - h o o k s - p h p - - h o o k f i l e s t e s t s / d r e d d / h o o k s / h o o k f i l e . p h p
  48. REPOSITORIES " r e q u i r e "

    : { " b o s n a d e v / r e p o s i t o r i e s " : " 0 . * " } Container where data access logic is stored Hides the details of data access logic from business logic
  49. i n t e r f a c e R

    e p o s i t o r y I n t e r f a c e { p u b l i c f u n c t i o n a l l ( $ c o l u m n s = a r r a y ( ' * ' ) ) ; p u b l i c f u n c t i o n p a g i n a t e ( $ p e r P a g e = 1 5 , $ c o l u m n s = a r r a y ( ' * ' ) ) ; p u b l i c f u n c t i o n c r e a t e ( a r r a y $ d a t a ) ; p u b l i c f u n c t i o n u p d a t e ( a r r a y $ d a t a , $ i d ) ; p u b l i c f u n c t i o n d e l e t e ( $ i d ) ; p u b l i c f u n c t i o n f i n d ( $ i d , $ c o l u m n s = a r r a y ( ' * ' ) ) ; p u b l i c f u n c t i o n f i n d B y ( $ f i e l d , $ v a l u e , $ c o l u m n s = a r r a y ( ' * ' ) ) ; }
  50. u s e A p p \ R e p

    o s i t o r i e s \ F i l m R e p o s i t o r y a s F i l m ; c l a s s F i l m s C o n t r o l l e r e x t e n d s C o n t r o l l e r { / * * * @ v a r F i l m * / p r i v a t e $ f i l m ; p u b l i c f u n c t i o n _ _ c o n s t r u c t ( F i l m $ f i l m ) { $ t h i s - > f i l m = $ f i l m ; } p u b l i c f u n c t i o n i n d e x ( ) { r e t u r n \ R e s p o n s e : : j s o n ( $ t h i s - > f i l m - > a l l ( ) ) ;
  51. Basic actions are just enough for simple querying Added CriteriaInterface

    i n t e r f a c e C r i t e r i a I n t e r f a c e { p u b l i c f u n c t i o n s k i p C r i t e r i a ( $ s t a t u s = t r u e ) ; p u b l i c f u n c t i o n g e t C r i t e r i a ( ) ; p u b l i c f u n c t i o n g e t B y C r i t e r i a ( C r i t e r i a $ c r i t e r i a ) ; p u b l i c f u n c t i o n p u s h C r i t e r i a ( C r i t e r i a $ c r i t e r i a ) ; p u b l i c f u n c t i o n a p p l y C r i t e r i a ( ) ; }
  52. c l a s s L e n g t

    h O v e r T w o H o u r s i m p l e m e n t s C r i t e r i a I n t e r f a c e { p u b l i c f u n c t i o n a p p l y ( $ m o d e l , R e p o s i t o r y $ r e p o s i t o r y ) { $ q u e r y = $ m o d e l - > w h e r e ( ' l e n g t h ' , ' > ' , 1 2 0 ) ; r e t u r n $ q u e r y ; } }
  53. u s e A p p \ R e p

    o s i t o r i e s \ C r i t e r i a \ F i l m s \ L e n g t h O v e r T w o H o u r s ; u s e A p p \ R e p o s i t o r i e s \ F i l m R e p o s i t o r y a s F i l m ; c l a s s F i l m s C o n t r o l l e r e x t e n d s C o n t r o l l e r { / * * * @ v a r F i l m * / p r i v a t e $ f i l m ; p u b l i c f u n c t i o n _ _ c o n s t r u c t ( F i l m $ f i l m ) { $ t h i s - > f i l m = $ f i l m ; } p u b l i c f u n c t i o n i n d e x ( ) {
  54. CORS (CROSS-ORIGIN RESOURCE SHARING) " r e q u i

    r e " : { " b a r r y v d h / l a r a v e l - c o r s " : " ^ 0 . 7 . 2 " } Allows you to send CORS headers with ACL-style per-url configuration. Supports Laravel & Lumen
  55. RESOURCES - - - Laravel documentation Why choose Laravel Using

    Repository