RESETful API接口设计规范
最新回答
爷傲灬奈我何
2021-03-29 14:17:18
以下为贯穿全文的几个重要术语：资源（单个对象的实例，如动物）、集合（同类型对象的集合，如动物们）、HTTP（网络通信协议）、消费者（可发起HTTP请求的客户端应用程序）、第三方开发者（非项目组成员但希望使用数据的开发者）、服务（可通过网络访问的HTTP服务/应用）、节点（服务器上的API URL，可代表资源或整个集合）、幂等性（无副作用，可多次执行）、URL段（URL中由斜杠分隔的信息段）。
数据抽象与设计：需确定数据库设计及提供的web服务功能，以进行API设计。API应尽可能抽象业务逻辑和数据，以便使用者轻松上手。
请求方法：常见的HTTP请求方法有GET（检索资源）和POST（创建资源）。以下为四个半重要的HTTP动词：GET（检索）、POST（创建）、PUT（更新整个资源）、PATCH（更新资源属性）、DELETE（删除资源）。此外，还有HEAD（检索元数据）和OPTIONS（检索操作信息）。RESTful API应利用这些请求方法进行交互，且URL段中不包含任何动作。
版本控制：应用的核心和数据关联关系会不断变化，因此API版本控制至关重要。修改API可能导致向后不兼容，影响使用者。为确保应用发展并满足使用者需求，需在引入新版本的同时保证旧版本的正常访问。
API分析：持续跟踪客户端使用的API版本和端点信息，如每次请求自增计数器。跟踪API有助于保证常用API的有效性。
API Root URL：API根地址对开发者至关重要。保持根入口点简单可提高开发者接受度。根据应用规模，API可放置于子域或根域名下，并包含相关内容。
端点：端点指向特定资源或资源集合的URL。针对每个端点，需列出有效的HTTP动词和端点组合。
过滤器：当客户端请求对象列表时，返回符合查询条件的所有对象列表。过滤器可最小化网络传输并加快查询结果获取。
状态码：使用合适的HTTP状态码对RESTful API至关重要。常见状态码包括200 OK、201 CREATED、204 NO CONTENT等。
状态码范围：1xx范围状态码用于底层HTTP功能，2xx范围状态码用于成功消息，3xx范围状态码用于重定向，4xx范围状态码用于客户端错误，5xx范围状态码用于服务器端错误。
预期返回文档：使用不同的HTTP动词执行动作时，消费者需要在返回中获取某些信息。典型的RESTful API包括GET、POST、PUT、PATCH、DELETE等操作。
认证：服务器需确定进行请求的用户身份。OAuth2.0等认证方法可确保客户端安全访问API。
Content Type：大多数API提供JSON数据支持。返回有效的数据格式可让开发者使用流行的语言和框架进行解析。
超媒体API：超媒体API可能是RESTful API设计的未来。它通过请求API根获取URL列表，每个URL都指向一个集合，并描述客户端可理解的信息。
文档：API文档对开发者至关重要。文档应面向所有开发者，确保易于理解，并提供完整的示例请求和响应主体。
勘误：原始的HTTP封装：HTTP请求和响应都由键值对集组成，包括头部、请求体、响应体等。使用工具查看原始HTTP封装对API设计至关重要。
热门标签
