README

介绍 RESTER，一个旨在简化 REST API 交互的 Laravel 包，提供了一种无缝且优雅的方式来处理 API 调用。受 Laravel 的 Eloquent 模型方法启发，此包允许开发者为每个 API 调用定义一个模型，与 Laravel 的表模型熟悉的结构相似。

此外，该包支持将相关的 API 调用分组到一个共同的父类下，增强代码组织和可重用性。通过将 REST API 逻辑封装到可管理的模型中，开发人员可以轻松地集成外部服务。

简介

在本文档中，我们将通过示例 API PaynowPaymentGateway 展示如何使用 RESTER，重点关注 PayNowCreateOrder 类。使用简单且优雅的语法，您可以将 API 调用抽象为可管理、可重用的对象。

要安装 RESTER 包，请使用 Composer

composer require itsmg/rester

1. 使用最小代码进行 API 调用

使用 RESTER，您可以只用一行代码调用 API。以下是如何在 PaynowPaymentGateway 示例中获取订单创建 API 的方法

$response = PayNowCreateOrder::fetch();

这一行代码处理了所有操作——从发送请求到处理响应。PayNowCreateOrder 类封装了 API 调用所需的所有必要细节。

2. 封装 API 逻辑，关注业务逻辑

开发者应专注于业务逻辑，而 RESTER 处理 API 交互。您可以将 API 调用逻辑封装在单独的类中，保持您的业务逻辑清晰且易于维护。

Artisan 命令用于创建 API 调用类

php artisan rester:create --group=PaynowPaymentGateway --api-name=PayNowCreateOrder

此命令在 app/Rester/PaynowPaymentGateway/ 目录下生成新的 PayNowCreateOrder 类（如果已存在则跳过创建分组文件夹）。

示例类：PayNowCreateOrder

namespace App\Rester\PaynowPaymentGateway;

use Itsmg\Rester\Rester;
use Itsmg\Rester\Contracts\HasFinalEndPoint;

class PayNowCreateOrder extends Rester implements HasFinalEndPoint
{
    public function setFinalEndPoint(): string
    {
        return 'https://example-paynow.com/api/v1/create/order';
    }
}

3. 为 API 调用分配默认有效载荷

您可以分配每个请求的默认有效载荷。例如，创建订单时，您可能需要传递金额、货币和用户 ID。

class PayNowCreateOrder extends Rester implements HasFinalEndPoint, WithDefaultPayload
{
    public function setFinalEndPoint(): string
    {
        return 'https://example-paynow.com/api/v1/create/order';
    }

    public function defaultPayload(): array
    {
       return [ 
         'user_id' => 'itsmg@1606',
         'amount' => '1994.00,
         'currency' => 'USD',
       ];
    }
}

现在，每次调用 PayNowCreateOrder 时，它都会自动发送默认有效载荷，除非被覆盖。

4. 为 API 调用分配默认头信息

头信息，如身份验证令牌，可以默认设置，确保它们与每个请求一起发送

class PayNowCreateOrder extends Rester implements HasFinalEndPoint, WithRequestHeaders
{
    public function setFinalEndPoint(): string
    {
        return 'https://example-paynow.com/api/v1/create/order';
    }

    public function defaultRequestHeaders(): array
    {
       return [ 
         'Content-Type' => 'application/json',
         'Authorization' => 'Bearer ' . PayNowAuthToken::fetch()
       ];
    }
}

在此处，使用身份验证令牌 API 调用自动附加 Authorization 头信息，使开发过程对开发者来说无缝。

5. 动态处理有效载荷和头信息

您可以在运行时轻松地动态地自定义有效载荷或头信息。以下是一个示例

动态添加有效载荷

$response = (new PayNowCreateOrder())
           ->addPayloads(['secret-key' => 'xxxxxxx'])
           ->send()
           ->get();

动态添加头信息

$response = (new PayNowCreateOrder())
           ->addHeaders(['Content-Type' => 'application/json'])
           ->send()
           ->get();

这种灵活性允许您根据应用程序的状态传递动态数据和头信息。

6. 探索 RESTER 构建方法

RESTER 还提供了构建方法以进一步增加灵活性

overWriteEndPoint：如果需要，则覆盖默认端点。
appendEndPoint：将附加段附加到端点。
assignBaseUri：为所有 API 调用设置基本 URI。
assignApiRoute：定义特定的 API 路由。

这些方法使您可以对 API URL 实现完全控制，随着应用程序复杂性的增长。

7. 有效载荷和头信息拦截

RESTER 提供了一个强大的功能，在 API 调用启动之前拦截有效载荷或头信息，使实现验证规则、缓存或格式化变得容易。您还可以在将响应内容返回到业务逻辑之前拦截和修改响应内容。

示例：拦截有效载荷

class PayNowCreateOrder extends Rester implements HasFinalEndPoint, PayloadInterceptor
{
    public function setFinalEndPoint(): string
    {
        return 'https://example-paynow.com/api/v1/create/order';
    }

    public function interceptPayload($payload): array
    {
       $this->exampleValidator($payload);

       return [ 
         'encrypted-data' => $this->exampleEncryptionLogic($payload)
       ];
    }
}

在此示例中，您可以在发送之前验证和加密有效载荷。

8. API 访问日志

RESTER 包含 API 访问日志功能。您可以使用 $log 属性来启用或禁用该功能，并指定应记录哪些详细信息。

class PayNowCreateOrder extends Rester implements HasFinalEndPoint
{
    protected bool $log = true;

    public function setFinalEndPoint(): string
    {
        return 'https://example-paynow.com/api/v1/create/order';
    }
}

此功能允许您跟踪 API 交互，用于调试或审计目的。

结论

使用 RESTER，Laravel 中的 API 集成变得非常简单。无论是发送动态有效负载、管理身份验证还是记录 API 访问，RESTER 都允许您通过将 REST API 调用的复杂性抽象为可重用、可管理的组件，从而专注于业务逻辑。

安全漏洞

如果您在 Rester 中发现安全漏洞，请通过电子邮件将漏洞信息发送至 Balamurugan，邮箱地址为 balaneutro@gmail.com。所有安全漏洞都将得到及时处理。

itsmg / rester

维护者

详细信息