设计良好 API 感觉不可见，它只是工作。在那个简单性背后是一套一致设计原则使 API 可预测、安全和可扩展。

好 API vs. 糟糕 API

1. 幂等性（Idempotency）

  • GET、HEAD、PUT 和 DELETE 应该幂等
  • 发送相同请求两次，获得相同结果
  • 没有意外副作用
  • POST 和 PATCH 不幂等
  • 每个调用创建新资源或修改状态不同
  • 使用幂等键存储在 Redis 或你数据库
  • 客户端发送相同键与重试，服务器识别它并返回原始响应代替再次处理

2. 版本控制（Versioning）

  • API 应该有版本控制
  • 例如：/v1/products、/v2/products

3. 基于名词资源名（Noun-based resource names）

  • 资源应该是名词，不是动词
  • “/api/products”，不是”/api/getProducts”

4. 安全（Security）

  • 保护每个端点有适当认证
  • Bearer 令牌（如 JWTs）包括头部、负载和签名验证请求
  • 总是使用 HTTPS 并验证令牌在每个调用

5. 分页（Pagination）

  • 当返回大数据集，使用分页参数如”?limit=10&offset=20”
  • 保持响应高效和一致

大数据管道速查表

每个平台提供全面服务套件覆盖整个生命周期：

阶段

  • Ingestion：从各种来源收集数据
  • Data Lake：存储原始数据
  • Computation：处理和分析数据
  • Data Warehouse：存储结构化数据
  • Presentation：可视化和报告洞察

AWS

  • Streaming：Kinesis
  • Storage：S3
  • Processing：EMR
  • Warehousing：RedShift
  • Visualization：QuickSight

Azure

  • Ingestion：Event Hubs
  • Storage：Data Lake Store
  • Processing：Databricks
  • Warehousing：Cosmos DB
  • Visualization：Power BI

GCP

  • Streaming：PubSub
  • Storage：Cloud Storage
  • Processing：DataProc、DataFlow
  • Warehousing：BigQuery
  • Visualization：Data Studio

AWS 学习地图

AWS 是最流行云平台之一。当 AWS 宕机，互联网大部分宕机。

AWS 基础

  • “什么是 AWS？”
  • 全球基础设施
  • AWS 计费、管理
  • IAM 基础

核心计算、存储和网络

  • 计算服务：EC2、Lambda、ECS、EKS
  • 存储服务：S3、EBS、EFS、Glacier
  • 网络服务：VPC、ELB、Route 53

数据库和数据服务

  • 关系数据库：RDS MySQL、PostgreSQL
  • NoSQL：DynamoDB
  • 内存数据库：ElastiCache（Redis、Memcached）

安全、身份和合规

  • IAM 深入
  • 加密：KMS、S3 SSE
  • 安全工具
  • VPC 安全组
  • 合规模工具：HIPAA、SOC、GDPR

DevOps、监控和自动化

  • DevOps 工具：CodeCommit、CodeBuild、CodePipeline
  • 基础设施即代码
  • CI/CD 管道
  • 监控工具：CloudWatch、CloudTrail
  • 成本管理和计费仪表板

学习路径和认证

  • AWS 学习资源：Skill Builder、文档
  • 认证路径：
    • Cloud Practitioner
    • Solutions Architect Associate
    • Developer Associate
    • SysOps
    • DevOps Engineer

AI Agent 技术栈

基础模型（Foundation Models）

  • 大规模预训练语言模型
  • 作为 AI 代理”大脑”
  • 启用能力如推理、文本生成、编码、问答

数据存储（Data Storage）

  • 向量数据库和记忆存储系统
  • AI 代理存储和检索上下文、嵌入或文档

代理开发框架（Agent Development Frameworks）

  • 帮助开发者构建、编排和管理多步 AI 代理和它们工作流

可观察性（Observability）

  • 启用监控、调试和日志记录 AI 代理行为和性能在实时

工具执行（Tool Execution）

  • 这些平台允许 AI 代理接口与现实世界工具（例如，API、浏览器、外部系统）完成复杂任务

记忆管理（Memory Management）

  • 这些系统管理长期和短期记忆为代理
  • 帮助它们保留有用上下文和从过去交互学习

在 AWS 上构建基本 RAG 应用

RAG 是 AI 模式结合搜索步骤与文本生成。它检索相关信息从知识源（如向量数据库）然后使用 LLM 生成准确、上下文感知响应。

Ingestion 阶段

  1. 所有原始文档（PDFs、文本等）首先存储在 Amazon S3
  2. 当文件添加，AWS Lambda 运行 ingestion 函数
  3. 这个函数清理和分裂文档为小块
  4. 每个块发送到 Amazon Bedrock 的 Titan 嵌入模型，转换它为向量表示
  5. 这些嵌入，与元数据一起，存储在向量数据库如 OpenSearch serverless、DynamoDB

Querying 阶段

  1. 用户发送问题通过应用前端，它去 API Gateway 然后 Lambda 查询函数
  2. 问题转换为嵌入使用 Amazon Bedrock Titan Embeddings
  3. 这个嵌入比较对抗存储文档嵌入在向量数据库找到最相关块
  4. 最相关块和用户问题发送到 LLM（如 Claude 或 OpenAI on Bedrock）生成答案
  5. 生成响应发送回用户通过相同 API

本文为学习目的的个人翻译，译文仅供参考。

原文链接：EP189: How to Design Good APIs。

版权归原作者或原刊登方所有。本文为非官方译本；如有不妥，请联系删除。