README

此包提供使用Laravel资源和其它API辅助函数（如API请求验证）进行API响应格式化的功能。

API资源格式

保持一个通用的响应格式是良好的实践。本包使用以下格式：

<?php

namespace aliirfaan\LaravelSimpleApi\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

/**
 * ApiResponseCollection
 * 
 * A format for API responses
 * success: bool | whether response is success or failure
 * result: response main body
 * errors: response errors
 * links: HATEOS links
 * message: response diaply message
 * extra: any extra data
 */
class ApiResponseCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        $items = $this->collection->all();
        return [
            'success' => $items['success'] ?? false,
            'result' => $items['result'] ?? null,
            'errors' => $items['errors'] ?? null,
            'links' => $items['links'] ?? null,
            'message' => $items['message'] ?? null,
            'extra' => $items['extra'] ?? null
        ];
    }
}

错误响应格式

所使用的错误响应格式受到了paypal api指南的启发

特性

为您的API获取一个通用的响应格式
API错误响应格式化
API请求验证
所有消息都已本地化

要求

Composer
Laravel
PHP >= 7.0.0

安装

您可以使用Composer将此包安装到现有的Laravel项目中

 $ composer require aliirfaan/laravel-simple-api

通过编辑config/app.php文件并添加到提供者数组中来注册ServiceProvider

  aliirfaan\LaravelSimpleApi\SimpleApiServiceProvider::class,

注意：Laravel <5.1版本使用以下内容

 'aliirfaan\LaravelSimpleApi\SimpleApiServiceProvider',

使用以下命令发布文件

 $ php artisan vendor:publish --provider="aliirfaan\LaravelSimpleApi\SimpleApiServiceProvider"

或者仅使用php artisan vendor:publish，并从输出列表中选择aliirfaan\LaravelSimpleApi\SimpleApiServiceProvider

用法

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\User;
use aliirfaan\LaravelSimpleApi\Services\ApiHelperService;
use Symfony\Component\HttpFoundation\Response;

class TestController extends Controller
{
    public function testApiHelper(Request $request, ApiHelperService $apiHelperService)
    {
        // get your api request fields
        $requestArray = $request->json()->all();

        // get your validatin rules
        $validationRules = User::$createRules;

        //validate api request
        $validationResult = $apiHelperService->validateRequestFields($requestArray, $validationRules);
        if (!is_null($validationResult)) {
            // output error response
            $namespace = 'user';
            $validationErrorResponse = $apiHelperService->apiValidationErrorResponse($namespace, $validationResult);
            return $validationErrorResponse->response()->setStatusCode(Response::HTTP_BAD_REQUEST);
        }

        // use your own message key
        if (!is_null($validationResult)) {
            // output error response
            $namespace = 'user';
            $errorTranslationKey = 'auth.failed';
            $errorTranslationParameters = ['code' => '15645'];

            $validationErrorResponse = $apiHelperService->apiValidationErrorResponse($namespace, $validationResult, $errorTranslationKey, $errorTranslationParameters);
            return $validationErrorResponse->response()->setStatusCode(Response::HTTP_BAD_REQUEST);
        }

        // a general response
        $data = $apiHelperService->responseArrayFormat;
        //dd($data);

        // do your processing
        $data['success'] = true;
        $result = new ApiResponseCollection($data);
        return $result->response()->setStatusCode(Response::HTTP_OK);
    }
}

常见API错误的响应

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\User;
use aliirfaan\LaravelSimpleApi\Services\ApiHelperService;
use Symfony\Component\HttpFoundation\Response;

class TestController extends Controller
{
    public function testApiHelper(Request $request, ApiHelperService $apiHelperService)
    {
        $namespace = $this->customerApiCommandModel->namespace;

        // database error
        $errorResource = $apiHelperService->apiDatabaseErrorResponse($namespace);
        return $errorResource->response()->setStatusCode($errorResource->collection['status_code']);

        // unknown/general error
        $errorResource = $apiHelperService->apiUnknownErrorResponse($namespace);
        return $errorResource->response()->setStatusCode($errorResource->collection['status_code']);

        // authentication error
        $errorResource = $apiHelperService->apiAuthenticationErrorResponse($namespace);
        return $errorResource->response()->setStatusCode($errorResource->collection['status_code']);

        // authorization error
        $errorResource = $apiHelperService->apiAuthorizationErrorResponse($namespace);
        return $errorResource->response()->setStatusCode($errorResource->collection['status_code']);

        // processing error with issue
        $issues = ['This is an issue', 'There is another issue'];
        $errorDetails[] = [
            'issues' => $issues
        ];
        $errorResource = $apiHelperService->apiProcessingErrorResponse($namespace, $errorDetails);
        return $errorResource->response()->setStatusCode($errorResource->collection['status_code']);
    }
}

有效的错误响应示例

{
    "data": {
        "success": false,
        "result": null,
        "errors": [
            {
                "name": "VALIDATION_ERROR",
                "message": "Invalid data provided",
                "debug_id": "test-GRCrDMYlbzNqXlRX",
                "details": [
                    {
                        "field": "is_citizen",
                        "value": null,
                        "issues": [
                            "The is citizen field is required."
                        ],
                        "links": null
                    },
                    {
                        "field": "mobile_number",
                        "value": null,
                        "issues": [
                            "The mobile number field is required."
                        ],
                        "links": null
                    }
                ]
            }
        ],
        "links": null,
        "message": "Processing could not be completed due to an error.",
        "extra": null
    }
}

未知错误响应示例

{
    "data": {
        "success": false,
        "result": null,
        "errors": [
            {
                "name": "UNKNOWN_ERROR",
                "message": "Processing could not be completed due to an unknown error.",
                "debug_id": "test-k4PjPxwZ9aVt4Xqs",
                "details": [
                    {
                        "field": null,
                        "value": "a value",
                        "issues": [
                            "This is an issue",
                            "There is another issue"
                        ],
                        "links": null
                    }
                ]
            }
        ],
        "links": null,
        "message": "Processing could not be completed due to an error.",
        "extra": null
    }
}

许可证

MIT许可证（MIT）

在此，免费许可任何获得本软件及其相关文档副本（“软件”）的人，在不受限制的情况下使用软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许向软件提供副本的人这样做，前提是遵守以下条件：

aliirfaan / laravel-simple-api

维护者

详细信息