Building a RESTful API with Laravel Saad EL HAJJAJI saadel.me - @_saadel - github.com/saadel 

Application Programming Interface Building a RESTful API 

REpresentational State Transfer Building a RESTful API 

Resource-based Building a RESTful API Things vs. Actions Nouns vs. Verbs 

Representations Building a RESTful API Transferred between client and server Typically JSON or XML 

Constraints Building a RESTful API • Uniform Interface • Stateless HTTP Verbs / URIs / HTTP Responses • Client-Server • Cacheable • Layered System Server Responses • Code On Demand 

Building a RESTful API with Laravel 

Building a RESTful API with Laravel github.com/saadel/mphpa-blog-api Code available on GitHub 

1. Planning 2. Building 3. Tweaking 

1. Planning 

1 1 1 1..* 1..* 1..* 

No content

Action Plan 

Action Plan Users - Create - Read - Update - Delete - List - Posts - Comments Posts - Create - Read - Update - Delete - List - Comments Comments - Create - Read - Update - Delete - List 

Endpoints 

Endpoints /{resource}/{id} /{resource}/{id}/{sub-resource}/{id} 

Endpoints /users/1 /users/1/posts/3 

Endpoints /posts/2 /posts/2/comments/4 

Endpoints /posts /posts/2 /posts/2/comments /posts/2/comments/4 

2. Building 

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 

Displaying Data 

The Direct Approach Post::find($id)->toArray(), ]); } public function index() { return json_encode([ 'data' => Post::all()->toArray(), ]); } } 

Formatting Data [ 'id' => (int) $post->id, 'title' => $post->title, 'content' => $post->content, 'created_at' => (string) $post->created_at, ], ]); } } 

Fractal 

Fractal Output complex, flexible, AJAX/RESTful data structures. 

Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 

Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers 

Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers 2. Create ApiController 

Fractal Output complex, flexible, AJAX/RESTful data structures. $ composer require league/fractal 1. Create Transformers 2. Create ApiController 3. Update Controllers 

No content

(int) $post->id, 'content' => $post->content, 'created_at' => (String) $post->created_at, ]; } } 

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; } 

ApiController protected function respondWithError($message, $errorCode) { return $this->respondWithArray([ 'error' => [ 'code' => $errorCode, 'http_code' => $this->statusCode, 'message' => $message, ] ]); } } 

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); } } 

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'); 

Resource Groups Action Create Read Update Delete List Endpoint POST /posts GET /posts/X PUT /posts/X DELETE /posts/X GET /posts 

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 ); } 

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 ); } 

DELETE /posts/X public function destroy($id) { $post = Post::find($id); $post->delete(); return response()->json([ "msg" => "Success", ], 200 ); } 

Errors 

Error { “error”: { “code”: "GEN-NOTFOUND", “http_code”: 404, “message”: "A post with this ID doesn't exist." } } 

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, … 

Data Relationships 

Sub-Resources /posts/1/comments 

Foreign Key Arrays { "post": { "id": 1 "title": "Progressive Enhancement is Dead", "comments": ["1", "2"], "_links": { "user": "/people/saadel" } } } 

Embedded Documents comments; return $this->collection($comments, new CommentTransformer); } // embedUser… } 

3. Tweaking 

Versioning 

v1/users/1 v1/posts/1?embed=comments 

// app/Http/routes.php Route::group(array('prefix' => 'v1', function() { // Routes here... }); 

Documentation 

Documentation Swagger apiblueprint 

Debugging 

Debugging Command-line debugging curl -X POST http://localhost/users/gf325/posts --data
 @payload.json 

Debugging Browser debugging HTTP Clients or REST Clients Clockwork 

POSTMAN 

Clockwork 

Debugging Network debugging 

Resources Build APIs you won’t hate by Phil Sturgeon REST API Design Rulebook by Mark Masse REST API concepts and examples 

Closing Thoughts 

thanks ! Saad EL HAJJAJI saadel.me - @_saadel - github.com/saadel