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）
• 认证（Bearer 令牌）和 CRUD 操作的授权
• 支持资源包含、分页等 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。

贡献

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

发送拉取请求有两种方式

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

许可证

Apache许可证（版本2.0）。有关更多信息，请参阅许可证文件。