nicklaw5/larapi

A simple Laravel 5 class for handling json api responses.

3.0.1 2017-02-03 19:35 UTC

Requires

• php: >=5.5.9

MIT

• Nicholas Law

• json
• api
• response
• laravel

README

A simple Laravel 5 package for handling common HTTP API responses in JSON form.

Docs

You can find v2.x docs here. For the lastest (v3.x) docs see below.

Installation

Pull in Larapi via composer:

$ composer require nicklaw5/larapi

Then, add the following Service Provider to your providers array in your config/app.php file:

'providers' => array(
	...
	Larapi\LarapiServiceProvider::class,
);

Usage

###Succes Responses### Available responses:

Larapi::ok();           // 200 HTTP Response
Larapi::created();      // 201 HTTP Response
Larapi::accepted();     // 202 HTTP Response
Larapi::noContent();    // 204 HTTP Response

Example: Return HTTP OK

This:

// app/Http/routes.php

Route::get('/', function()
{
	return Larapi::ok();
});

will return:

{
	"success": true
}

with these headers:

HTTP/1.1 200 OK
Content-Type: application/json

Example: Return HTTP OK with Response Data

This:

// app/Http/routes.php

Route::get('/', function()
{
	$data = [
		['id' => 1, 'name' => 'John Doe', 'email' => '[e-mail]'],
		['id' => 2, 'name' => 'Jane Doe', 'email' => '[e-mail]']
	];

	return Larapi::ok($data);
});

will return:

{
	"success": true,
	"response": [
		{
			"id": 1,
			"name": "John Doe",
			"email": "[e-mail]"
		},
		{
			"id": 2,
			"name": "Jane Doe",
			"email": "[e-mail]"
		}
	]
}

with these headers:

HTTP/1.1 200 OK
Content-Type: application/json

Example: Return HTTP OK with Custom Response Headers

This:

// app/Http/routes.php

Route::get('/', function()
{
	$data = [
		['id' => 1, 'name' => 'John Doe', 'email' => '[e-mail]'],
		['id' => 2, 'name' => 'Jane Doe', 'email' => '[e-mail]']
	];

	$headers = [
		'Header-1' => 'Header-1 Data',
		'Header-2' => 'Header-2 Data'
	];

	return Larapi::ok($data, $headers);
});

will return:

{
	"success": true,
	"response": [
		{
			"id": 1,
			"name": "John Doe",
			"email": "[e-mail]"
		},
		{
			"id": 2,
			"name": "Jane Doe",
			"email": "[e-mail]"
		}
	]
}

with these headers:

HTTP/1.1 200 OK
Content-Type: application/json
Header-1: Header-1 Data
Header-2: Header-2 Data

###Error Responses###

Available responses:

Larapi::badRequest();           // 400 HTTP Response
Larapi::unauthorized();         // 401 HTTP Response
Larapi::forbidden();            // 403 HTTP Response
Larapi::notFound();             // 404 HTTP Response
Larapi::methodNotAllowed();     // 405 HTTP Response
Larapi::conflict();             // 409 HTTP Response
Larapi::unprocessableEntity();  // 422 HTTP Response
Larapi::internalError();		// 500 HTTP Response
Larapi::notImplemented();       // 501 HTTP Response
Larapi::notAvailable();         // 503 HTTP Response

Example: Return HTTP Bad Request

This:

// app/Http/routes.php

Route::get('/', function()
{
	return Larapi::badRequest();
});

will return:

{
	"success": false
}

with these headers:

HTTP/1.1 400 Bad Request
Content-Type: application/json

Example: Return HTTP Bad Request with Custom Application Error Message

This:

// app/Http/routes.php

Route::get('/', function()
{
	$errorCode = 4001;
	$errorMessage = 'Invalid email address.';

	return Larapi::badRequest($errorMessage, $errorCode);
});

will return:

{
	"success": false,
	"error_code": 4001,
	"error": "Invalid email address."
}

with these headers:

HTTP/1.1 400 Bad Request
Content-Type: application/json

Example: Return HTTP Bad Request with An Array of Errors and Custom Response Headers

This:

// app/Http/routes.php

Route::get('/', function()
{
	$errorCode = 4001;
	$errors = [
		'email' => 'Invalid email address',
		'password' => 'Not enough characters',
	];

	$headers = [
		'Header-1' => 'Header-1 Data',
		'Header-2' => 'Header-2 Data'
	];

	return Larapi::badRequest($errors, null, $headers);
});

will return:

{
	"success": false,
	"errors": {
		"email": "Invalid email address",
		"password": "Not enough characters"
	}
}

with these headers:

HTTP/1.1 200 OK
Content-Type: application/json
Header-1: Header-1 Data
Header-2: Header-2 Data

License

Larapi is licensed under the terms of the MIT License.

TODO

• test, test, test