21、API设计与版本管理的实用建议

API设计与版本管理的实用建议

1. 超媒体与API设计

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

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

2. 标准名称的优势

以应用语义中“一个人的名字”为例，在第一步可能会根据数据库模式或数据模型中的相应字段给它一个临时名称，如 first_name、firstname 等。但到了第三步，需要考虑现有的描述人名的标准。例如，hCard 标准规定人名的语义描述符是 given - name，xCard 标准是 given，FOAF 标准是 givenName（在解释遗留数据时也可使用 firstName），schema.org 的 Person 项只允许使用 givenName。

这些标准虽然相互冲突，但不应再自创名称使情况更糟，而应选择与API应用语义最匹配的标准并使用其定义的名称。因为这些标准的设计者考虑了一些容易被忽略的概念陷阱，比如“名字”在不同文化中的含义不同，“given name”是更合适的语义描述符。采用标准名称对用户和开发者都有益，用户无需学习同一事物的不同名称，开发者也可在不改变API的情况下更改内部名称。

3. 设计媒体类型

设计新的媒体类型的优势在于能完全控制客户端处理文档的方式。不必基于XML、JSO