21、API设计建议与版本管理策略

API设计建议与版本管理策略

1. 超媒体与自定义API

在设计API时，如果是为自己使用，那么可以随心所欲。超媒体具有机器可读的特性，用户能够借助标准库对其进行管理，这就避免了他们误解文字说明的可能性。而且由于超媒体是在运行时提供的，在不影响客户端的情况下，对其控制进行修改有很大的灵活性，这是将相同信息放在API文档中所无法做到的。

美观的URL固然不错，但它们只是表面的，不会影响API的功能。即使所有美观的URL突然被随机生成的URL取代，API客户端也应该能够继续正常工作。

2. 采用标准名称

假设应用语义包含“一个人的名字”，在第一步中，可能会根据数据库模式或数据模型中的相应字段，给它一个临时名称，比如 first_name、firstname、first - name、fn、first name、first、fname 或 given_name。但到了第三步，需要考虑现有的描述人名的标准，并采用其中一个。

以下是不同标准对人名的描述：
| 标准 | 人名语义描述符 |
| ---- | ---- |
| hCard 标准 | given - name |
| xCard 标准 | given |
| FOAF 标准 | givenName（解释遗留数据时可用 firstName） |
| schema.org Person 项 | givenName |

这些标准虽然相互冲突，但没必要再创造新的名称来使情况变得更糟。应该选择一个与API应用语义整体最匹配的标准，并使用其定义的名称。例如，“first name” 并不是一个准确的术语，它是西方文化的