README

描述

一个优秀的 API 是提高客户体验最有效的方式之一。对数据格式和通信协议的标准化方法可以增加生产力，并使应用程序之间的集成变得顺畅。

这个无框架约束的包实现了 JSON API 规范 版本 v1.1，并帮助您专注于核心应用程序功能，而不是协议实现。它支持文档结构、错误、数据获取，如 JSON API 格式 中所述，并涵盖了解析和检查 HTTP 请求参数和头。例如，它有助于正确响应无效请求的 Unsupported Media Type（HTTP 状态码 415）和 Not Acceptable（HTTP 状态码 406）。您不需要在每次请求上手动验证所有输入参数。您可以配置您的服务支持哪些参数，并且这个包将自动检查传入的请求。它极大地简化了 API 开发，并完全支持规范。特别是

• 资源属性和关系
• 多态资源数据和关系
• 包含相关资源的复合文档（支持循环资源引用）
• 文档、资源、错误、关系和链接对象的元信息
• 配置文件
• 根据 RFC 7231 解析 HTTP Accept 和 Content-Type 头
• 解析 HTTP 查询参数（例如，分页、排序等）
• 稀疏字段集和自定义包含路径
• 错误

高代码质量和 100% 测试覆盖率，拥有 150+ 测试。生产就绪。

要了解更多信息，请查看 Wiki 和 示例应用程序.

“我喜欢它使快速实现 API 变得如此简单”

– Jeremy Cloutier

全栈集成

此包无框架约束，如果您想查看实际使用示例，您可能会对快速启动 JSON API 服务器应用程序 Limoncello App 感兴趣。

服务器支持

• 对一些示例数据模型和用户的 CRUD 操作。
• 对 API 服务器的跨域请求（CORS）。
• CRUD 操作的认证（Bearer 令牌）和授权。
• 支持诸如资源包含、分页等 JSON API 功能。

示例用法

假设您有一个类型为 \Author 的 $author，您可以像这样将其编码为 JSON API

$encoder = Encoder::instance([
        Author::class => AuthorSchema::class,
    ])
    ->withUrlPrefix('http://example.com/api/v1')
    ->withEncodeOptions(JSON_PRETTY_PRINT);

echo $encoder->encodeData($author) . PHP_EOL;

将输出

{
    "data" : {
        "type"       : "people",
        "id"         : "123",
        "attributes" : {
            "first-name": "John",
            "last-name": "Doe"
        },
        "relationships" : {
            "comments" : {
                "links": {
                    "related" : "http://example.com/api/v1/people/123/comments"
                }
            }
        },
        "links" : {
            "self" : "http://example.com/api/v1/people/123"
        }
    }
}

AuthorSchema 提供有关资源属性的信息，可能看起来像这样

class AuthorSchema extends BaseSchema
{
    public function getType(): string
    {
        return 'people';
    }

    public function getId($author): ?string
    {
        return $author->authorId;
    }

    public function getAttributes($author, ContextInterface $context): iterable
    {
        return [
            'first-name' => $author->firstName,
            'last-name'  => $author->lastName,
        ];
    }

    public function getRelationships($author, ContextInterface $context): iterable
    {
        return [
            'comments' => [
                self::RELATIONSHIP_LINKS_SELF    => false,
                self::RELATIONSHIP_LINKS_RELATED => true,

                // Data include supported as well as other cool features
                // self::RELATIONSHIP_DATA => $author->comments,
            ],
        ];
    }
}

参数 http://example.com/api/v1 是一个 URL 前缀，它将应用于所有编码的链接，除非它们设置了标志，表明不要添加任何前缀。

参数 JSON_PRETTY_PRINT 是 PHP 预定义的 JSON 常量。

一个包含多个、嵌套、过滤对象的编码示例程序以及其他示例 在这里。

要获取更多高级用法，请查看 Wiki.

版本

当前版本是 4.x（PHP 7.1+），对于较旧的 PHP（PHP 5.5 - 7.0，HHVM），请使用版本 1.x。

有问题？

不要犹豫，检查问题或者发布一个新的。

需要帮助吗？

您计划添加JSON API并需要帮助吗？我们非常愿意与您联系sales@neomerx.com。

贡献

如果您发现任何在此包中未反映的规范变更，请发布一个问题。欢迎对文档和代码改进的拉取请求。

发送拉取请求有2种方式

• 小型拉取请求应作为1个提交发送到develop分支。
• 对于较大的拉取请求（例如，新功能），建议创建一个请求新分支的issue。当创建了一个名为feature/issueXX的新分支（其中XX是问题号）时，您应向此分支发送拉取请求。当功能完成时，该分支将被压缩并合并到develop分支，然后合并到master分支。

许可证

Apache许可证（版本2.0）。请参阅许可证文件以获取更多信息。