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。

贡献

如果您发现有任何规格更改没有反映在本包中，请发布一个问题。欢迎对文档和代码改进的pull requests。

发送pull requests有两种方式

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

许可证

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

oilstone / json-api

维护者

详细信息

README

描述

全栈集成

示例用法

版本

有问题吗？

需要帮助吗？

贡献

许可证