Building A RESTful API With Laravel

Transcript

1. Building a RESTful API with Laravel Saad EL HAJJAJI saadel.me - @_saadel - github.com/saadel
2. Application Programming Interface Building a RESTful API
3. REpresentational State Transfer Building a RESTful API
4. Resource-based Building a RESTful API Things vs. Actions Nouns vs. Verbs
5. Representations Building a RESTful API Transferred between client and server Typically JSON or XML
6. Constraints Building a RESTful API • Uniform Interface • Stateless HTTP Verbs / URIs / HTTP Responses • Client-Server • Cacheable • Layered System Server Responses • Code On Demand
7. Building a RESTful API with Laravel
8. Building a RESTful API with Laravel github.com/saadel/mphpa-blog-api Code available on GitHub
9. 1. Planning 2. Building 3. Tweaking
10. 1. Planning
11. 1 1 1 1..* 1..* 1..*
13. Action Plan
14. Action Plan Users - Create - Read - Update - Delete - List - Posts - Comments Posts - Create - Read - Update - Delete - List - Comments Comments - Create - Read - Update - Delete - List
15. Endpoints
16. Endpoints /{resource}/{id} /{resource}/{id}/{sub-resource}/{id}
17. Endpoints /users/1 /users/1/posts/3
18. Endpoints /posts/2 /posts/2/comments/4
19. Endpoints /posts /posts/2 /posts/2/comments /posts/2/comments/4
20. 2. Building
21. Status Codes 200: Success! 201: Resource created 204: Success, but no content to return 400: Request not fulfilled 401: Not authenticated 403: Refusal to respond 404: Not found 500: Other error
22. Displaying Data
23. The Direct Approach <?php class PostController extends Controller { public function show($id) { return json_encode([ 'data' => Post::find($id)->toArray(), ]); } public function index() { return json_encode([ 'data' => Post::all()->toArray(), ]); } }
24. Formatting Data <?php class PostController extends Controller { public function show($id) { $post = Post::find($id); return json_encode([ 'data' => [ 'id' => (int) $post->id, 'title' => $post->title, 'content' => $post->content, 'created_at' => (string) $post->created_at, ], ]); } }
25. Fractal
26. Fractal Output complex, flexible, AJAX/RESTful data structures.
27. Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal
28. Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers
29. Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers 2. Create ApiController
30. Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers 2. Create ApiController 3. Update Controllers
32. <?php namespace App\Transformers; use App\Post; use League\Fractal\TransformerAbstract; class PostTransformer extends TransformerAbstract { public function transform(Post $post) { return [ 'id' => (int) $post->id, 'content' => $post->content, 'created_at' => (String) $post->created_at, ]; } }
33. ApiController class ApiController extends Controller { protected $statusCode = 200; public function __construct(Manager $fractal) { $this->fractal = $fractal; } protected function respondWithItem($item, $callback) { //Create item then return it with respondWithArray() } protected function respondWithCollection($collection, $callback){ //Create Collection then return it with respondWithArray() } protected function respondWithArray(array $array, array $headers = []) { $response = response()->json($array, $this->statusCode, $headers); return $response; }
34. ApiController protected function respondWithError($message, $errorCode) { return $this->respondWithArray([ 'error' => [ 'code' => $errorCode, 'http_code' => $this->statusCode, 'message' => $message, ] ]); } }
35. Update Controllers class PostController extends ApiController { public function index() { $posts = Post::take(10)->get(); return $this->respondWithCollection($posts, new PostTransformer); } public function show($id) { $post = Post::find($id); return $this->respondWithItem($post, new PostTransformer); } }
36. Routes Route::get('/users', 'UserController@index'); Route::get('/users/{id}', 'UserController@show'); Route::get('/posts', 'PostController@index'); Route::get('/posts/{id}', 'PostController@show'); Route::get('/comments', 'CommentController@index'); Route::get('/comments/{id}', 'CommentController@show');
37. Resource Groups Action Create Read Update Delete List Endpoint POST /posts GET /posts/X PUT /posts/X DELETE /posts/X GET /posts
38. POST /posts public function store(Request $request) { $post = new Post(); $post->content = $request->content; $post->user = User::find($request->user_id); $post->save(); return response()->json([ "msg" => "Success", "id" => $post->id() ], 200 ); }
39. PUT /posts/X public function update(Request $request, $id) { $post = Post::find($id); $post->content = $request->content; $post->user = User::find($request->user_id); $post->save(); return response()->json([ "msg" => "Success", ], 200 ); }
40. DELETE /posts/X public function destroy($id) { $post = Post::find($id); $post->delete(); return response()->json([ "msg" => "Success", ], 200 ); }
41. Errors
42. Error { “error”: { “code”: "GEN-NOTFOUND", “http_code”: 404, “message”: "A post with this ID doesn't exist." } }
43. class ApiController extends Controller { const CODE_WRONG_ARGS = 'GEN-1WT45PO'; const CODE_NOT_FOUND = 'GEN-LPF2FV6'; const CODE_INTERNAL_ERROR = 'GEN-A9AR4H'; const CODE_UNAUTHORIZED = 'GEN-M36UI'; const CODE_FORBIDDEN = ‘GEN-23T7'; protected function respondWithError($message, $errorCode) { return $this->respondWithArray([ 'error' => [ 'code' => $errorCode, 'http_code' => $this->statusCode, 'message' => $message, ] ]); } public function errorNotFound($message = 'Resource Not Found') { return $this->setStatusCode(404)->respondWithError($message, self::CODE_NOT_FOUND); } public function errorUnauthorized($message = 'Unauthorized') { return $this->setStatusCode(401)->respondWithError($message, self::CODE_UNAUTHORIZED); } //errorForbidden, errorInternalError, …
44. Data Relationships
45. Sub-Resources /posts/1/comments
46. Foreign Key Arrays { "post": { "id": 1 "title": "Progressive Enhancement is Dead", "comments": ["1", "2"], "_links": { "user": "/people/saadel" } } }
47. Embedded Documents <?php namespace App\Transformers; use … class PostTransformer extends TransformerAbstract { protected $availableEmbeds = [ 'user', 'comments' ]; public function transform(Post $post) { //Formatting our data } public function embedComments(Post $post) { $comments = $post->comments; return $this->collection($comments, new CommentTransformer); } // embedUser… }
48. 3. Tweaking
49. Versioning
50. v1/users/1 v1/posts/1?embed=comments
51. // app/Http/routes.php Route::group(array('prefix' => 'v1', function() { // Routes here... });
52. Documentation
53. Documentation Swagger apiblueprint
54. Debugging
55. Debugging Command-line debugging curl -X POST http://localhost/users/gf325/posts --data
 @payload.json
56. Debugging Browser debugging HTTP Clients or REST Clients Clockwork
57. POSTMAN
58. Clockwork
59. Debugging Network debugging
60. Resources Build APIs you won’t hate by Phil Sturgeon REST API Design Rulebook by Mark Masse REST API concepts and examples
61. Closing Thoughts
62. thanks ! Saad EL HAJJAJI saadel.me - @_saadel - github.com/saadel