如何设计更具包容性的API

如今，科技可以改变生活。从让我们与大洲各地的亲人联系到简化日常任务，创新在塑造我们的体验方面发挥着巨大作用。然而，要让这种变化产生影响，它必须是包容性的。

这就是创建包容性 API 的想法发挥作用的地方。传统的 API 设计通常会忽略用户的母语、能力和设备兼容性，从而为某些人带来障碍。构建包容性 API 通过识别不同的用户并确保 API 可供所有人访问和使用来解决此问题。

创建包容性 API 不仅仅是勾选复选框 — 而是要为不同的用户创建一个受欢迎的环境。从术语到更易于访问的开发人员门户设计，让我们探索一些有助于指导这种方法的基本原则。

语言和术语：促进清晰度和尊重

API 应该清晰、尊重他人，并且无论背景如何，每个人都能理解。因此，您用来描述 API 的语言不应该带有偏见。例如，在创建示例用户名时，请避免使用暗示特定性别的名称（如“john123”或“mary”）。在演练、教程或博客文章中，不要假设主题的性别。相反，请使用性别中立的示例或占位符。

世界是由各种文化组成的。因此，技术语言应该具有文化敏感性。注意特定地区的习语、隐喻或语句。考虑使用一种通用语言来编写开发人员文档，这种语言可以跨越文化界限。许多技术作家正是出于这个目的而更喜欢使用全球英语。

此外，可访问性也是关键。残障人士依赖屏幕阅读器等辅助技术。使用清晰简洁的语言准确传达这些工具的含义。避免使用行话或模糊的技术术语。说明性注释和错误消息对于无缝用户体验也很重要。

以下是非包容性术语与包容性术语的一些示例：

主/从 -> 主/辅
白名单/黑名单 -> 允许名单/拒绝名单
工时 -> 人员工时或工作时间
健全性检查 -> 快速检查或置信度检查

通过用户体验可访问性打开大门

为确保提供包容性的 API 体验，请考虑在开发人员门户和文档中尽可能支持辅助设备和技术。使用无障碍富互联网应用程序 (ARIA) 功能为屏幕阅读器创建清晰的标签，并考虑为行动障碍用户提供键盘导航。

其他用户体验技巧和最佳实践有助于提高可访问性。例如，WCAG 提供了最佳颜色对比度指南，可帮助视力较差的用户。采用响应式设计原则，在台式机、笔记本电脑、平板电脑和智能手机上获得无缝体验。

最后，创建清晰且可操作的错误消息，描述问题并提供解决方案。这种帮助将使用户能够更有效地浏览您的 API。通过在开发人员资源中优先考虑这些可访问性机制，您可以创建一个包容性的 API，欢迎任何人参与数字世界。

灵活性和定制化：满足全球受众的需求

真正灵活的 API 必须满足各种用户的需求。实现这一目标的方法之一是支持多种身份验证方法，以满足用户偏好和安全需求。通过允许本地（语言选项）和国际交易（日期、时间和货币的数据格式选项）来承认 API 的全球性。这种灵活性使全球开发人员能够无缝集成您的 API，并为全球受众提供直观的体验。

文档和支持：用知识搭建桥梁

通过清晰的 API 支持弥补知识差距。创建用户友好的文档，避免使用专业术语并解释复杂的概念。提供各种编程语言的代码片段，以满足全球受众的需求。此外，探索其他选项，例如视频教程、交互式编码示例或社区会议。提供这种多样化的学习材料使用户可以选择他们喜欢的方法并更深入地了解您的 API 功能。

从理论到实践

到目前为止，这些原则纯属假设，所以让我们看看如何将它们转化为代码。

包容性命名约定

首先，让我们考虑如何将包容性引入命名约定。以下是示例路线：

@app.route('/master_control')

def master_control():

路线名称master_control使用了“master”一词，该词可能具有支配或控制的负面含义。以下是更具包容性的替代方案：

@app.route('/primary_control')

def primary_control():

# …

路线名称已更改为primary_control，这更加中性，避免了任何潜在的冒犯。在 API 路径名称中使用此类清晰中性的语言有助于让它们对更广泛的受众具有包容性。

辅助功能

现在，让我们考虑一下 API 设计如何帮助提高最终用户的可访问性。支持这一点的一种方法是在 JSON 响应主体中共享其他信息。

{

  "data": [

    {

      "id": 1,

      "name": "Product A",

      "aria-label": "Product A, price $19.99, 4.5-star rating"  // Improves screen reader support

    }

  ]

}

此aria-label属性已添加到产品对象。此属性为屏幕阅读器提供有关数据元素的更多上下文，使视障用户更易于访问 API。

灵活的身份验证

最后，提供不同的身份验证方式可以帮助向更广泛的用户群开放您的 API。请考虑以下几点：

def authenticate(request):

    if 'api_key' in request.headers:

        return authenticate_with_api_key(request)

    elif 'oauth_token' in request.headers:

        return authenticate_with_oauth(request)

    else:

        return authenticate_with_basic_auth(request)

此代码片段展示了一个身份验证函数，该函数检查请求标头中的不同身份验证方法。这种方法为开发人员提供了灵活性，使他们能够根据自己的需求选择最合适的身份验证方法。

当然，API 设计应该遵循安全最佳实践。BasicAuth和API密钥都有各自的安全弱点。因此，可用性必须与高级别安全性取得平衡。

包容性 API 设计案例研究

让我们深入研究现实世界中的 API 如何实现包容性实践，并探索 API 设计的宝贵资源。首先，考虑一下通信平台提供商Twilio如何在其 API 设计和面向开发人员的材料中支持包容性：

语言和词汇： Twilio 优先考虑清晰且尊重的语言。他们避免使用性别术语和文化问题，做出普遍理解的选择。
可访问性： Twilio 确保与屏幕阅读器和其他支持技术的兼容性。提供清晰的字体和具有适当颜色对比度的描述，以获得最佳的用户体验。
灵活性： Twilio 了解不同的用户需求，提供不同的身份验证方法。开发人员可以根据项目需求选择 API 密钥、OAuth 令牌或基本身份验证。
本地化和国际化： Twilio 通过支持本地化和国际化来满足全球受众的需求。这使世界各地的开发人员能够确保 API 无缝集成。

其他行业领导者同样提倡包容性 API 设计。例如，Google 在其API 设计指南中提供了构建包容性 API 的全面指南。它强调使用清晰简洁的语言，避免使用行话，并遵守可访问性标准。Google 的指南还涉及文化敏感性以及为错误消息提供背景的重要性。

微软还优先考虑其所有产品（包括 API）的可访问性。他们为开发人员提供工具和资源，以确保他们的 API 能够与辅助技术完美配合。他们的方法侧重于键盘导航、精确的屏幕阅读器交互和适当的颜色对比度，以实现最佳用户体验。

实施包容性 API 的挑战和解决方案

实现包容性 API 设计面临重大挑战，需要仔细考虑。平衡无障碍功能（例如详细的错误消息或 ARIA 属性）与性能优化的需求可能很复杂。添加这些元素可能会略微增加响应时间，从而可能影响用户体验。因此，找到正确的平衡至关重要。

此外，更新现有 API 以纳入包容性设计原则可能会引入重大变更，影响与现有集成的兼容性。为了缓解这种情况，可以采用具有明确弃用政策的逐步实施方法，或维护单独的 API 版本以实现向后兼容性。

此外，在更广泛地推出之前，先向有限的受众测试包容性设计功能，有助于收集有价值的反馈并最大限度地减少干扰。因此，在整个开发过程中让各种各样的用户参与进来对于识别和解决潜在的访问障碍至关重要。通过不断收集和分析用户反馈，开发人员可以识别 API 可能不清楚、无法访问或效率低下的地方。

通过仔细考虑这些挑战并实施适当的策略，开发人员可以创建包容性的 API，而不会影响性能或用户体验。

包容性 API 设计的未来趋势

创建包容性 API 是充分发挥技术潜力的基石。通过优先考虑可访问性、透明度和用户体验，我们可以构建能够赋能广泛个体并推动创新的 API。当 API 在设计时考虑到包容性时，它们就不仅仅是功能性工具了。它们推动积极的变化，打破障碍，并推动更公平的数字环境。

包容性 API 设计的前景在不断发展，令人兴奋的趋势即将出现。想象一下能够动态适应用户偏好和需求的 API。机器学习算法可以分析用户行为，并根据位置、设备或可访问性要求等因素建议替代 API 调用或数据格式。这将进一步个性化 API 体验并增强包容性。

其他新兴技术，如语音界面、增强现实 (AR) 和虚拟现实 (VR) 正在彻底改变人机交互，并可能为 API 带来更好的包容性和可用性。确保具有不同身体能力和条件的用户能够无缝使用这项新兴技术对于广泛采用至关重要。

这些趋势凸显了包容性 API 设计的动态特性。随着技术的发展，创建人人都能访问且易于使用的 API 的策略和技术也将不断发展。

文章来源：How to Design More Inclusive APIs