HR产品RESTful API参数不统一，求细粒度行业标准参考

直接给你整理行业内公认的RESTful API细粒度规范参考方向，以及解决当前参数不统一问题的实操范式：

一、过滤参数统一范式 #

• 所有区间类型过滤（比如日期、数值范围）统一采用嵌套结构：filters[字段名][from] 和 filters[字段名][to]，你现在用的生日过滤格式就很适合作为全API的标准，替换掉入职日期那种独立的xxx_from/xxx_to参数，保持结构一致。
• 等值过滤用 filters[字段名] = 目标值，多值匹配用 filters[字段名][] = 值1&filters[字段名][] = 值2，避免混用不同的参数格式。

二、分页参数通用规范 #

• 全API统一用一种分页模式：要么选page（当前页码）+per_page（每页条数），要么选offset（数据偏移量）+limit（单页返回条数），绝对不要在不同接口混用两种模式。
• 可以统一在响应里返回total_count（总数据量），放在响应头或者响应体的元数据节点里，方便客户端处理分页逻辑。

三、排序参数统一格式 #

• 用sort参数统一处理排序逻辑，格式为字段名:排序方向，比如sort=joined_date:desc表示按入职日期降序；多字段排序用逗号分隔，比如sort=birth_day:asc,joined_date:desc。
• 排序方向统一用asc（升序）和desc（降序），不要自定义其他标识，减少对接成本。

四、可参考的行业规范体系 #

• OpenAPI（原Swagger）：它的参数定义规则是行业广泛认可的标准，你可以基于它来约束所有API的参数结构，确保过滤、分页、排序规则的一致性。
• JSON:API：这套规范对资源查询的参数有明确的细粒度要求，包括过滤（filter）、分页（page）、排序（sort）的统一格式，不少成熟的HR SaaS产品都参考这套规范实现对外API。
• 微软REST API指南：里面对查询参数的设计有详细的实践建议，比如区间过滤的命名规则、分页参数的标准用法，很适合作为企业级API的设计参考。

内容的提问来源于stack exchange，提问作者Thilanka