Pocket-ID API分页查询参数的正确使用方式

在Pocket-ID项目的API使用过程中，开发者可能会遇到分页查询结果不符合预期的问题。本文深入分析该问题的原因，并提供正确的参数使用方式。

问题现象

当开发者尝试使用类似/api/oidc/clients?limit=5&page=2这样的参数进行分页查询时，API返回的结果并非预期的第6-10条记录，而是返回了全部1-20条记录。分页元数据显示当前页为1，每页显示20条，这与请求参数明显不符。

根本原因

经过深入分析，发现这是由于API参数命名规范导致的。Pocket-ID API实际使用的是嵌套参数结构，而非简单的平面参数。正确的参数格式应该是：

pagination[limit]=5&pagination[page]=2

这种设计遵循了更现代的API参数组织方式，允许将相关参数分组管理，提高了参数的可读性和可维护性。

影响范围

该问题不仅存在于OIDC客户端列表接口，同样影响用户组列表接口。此外，文档中提到的默认按名称排序的描述也存在不准确的情况。

解决方案

开发者应按照以下格式构造分页查询请求：

curl -L 'https://your-domain/api/oidc/clients?pagination[limit]=5&pagination[page]=2' \
-H 'Accept: */*' \
-H 'X-API-KEY: your-api-key'

最佳实践

1. 参数编码：在URL中使用嵌套参数时，确保正确编码方括号等特殊字符
2. 默认行为：不要依赖文档中描述的默认排序行为，必要时显式指定排序参数
3. 日志分析：注意API日志可能显示重复请求，这是正常现象，与分页功能无关
4. 版本兼容：该问题在v1.2.0版本中存在，后续版本会修正文档描述

总结

Pocket-ID项目采用了嵌套参数的设计理念，虽然初期可能因文档不准确导致使用困惑，但这种设计在复杂API场景下更具优势。开发者应适应这种参数结构，以获得最佳的使用体验。项目团队已确认将在下一版本中更新文档，确保与实际行为一致。