api设计 - 关于 RESTful API 的设计的几点疑问？

问题描述

问 题

1. 不同端所需的 API 可能存在差异，移动端（android,ios），web 端需要的 API 应该分开放吗？

2. API 的版本如何设计？

   2.1 API 的版本号标志一般都放在哪里？（URI, 还是header里的某个字段？）
   2.2 移动端发布新的小版本，例如fix一些bug，发布了v1.0.1，API 需要做什么样的调整（直接合并到http://a.com/api/v1 里吗）？
   2.3 移动端发布新的大版本，例如v1 - v2，API 需要做什么样的调整(另起v2目录，原有的v1的api的请求全都失效吗)？

3. API 的安全方面，服务端和客户端各需要做哪些事情？

4. 针对移动端 API 来说，服务端需要指定响应的状态码吗？还是只要没有异常，通通返回 200（移动端貌似需要增加解析状态码的操作？？）?

5. 状态码放在json中还是以HTTP状态码形式返回？

可能有一些问题的答案是：这几种方案都行

解决方案

restful API 设计建议参考我的文章：微服务指南走北（三）：Restful API 设计简述

下面简单回答下你的问题：

1. 既然不同端所需的API存在差异，那么建议分开放，这样也易于后期的统计等操作

2. 版本号设计：

• 制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。为了避免API的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。

• 最适合放置版本号的位置URL中，或者是头信息(HTTP Headers)中在 Accept 段中使用自定义类型(content type)与其他元数据(metadata)一起提交。

https://api.example.com/v1/
或
Accept: application/vnd.heroku+json; version=3

3. 安全方面

建议你参考如下文章：REST API 安全设计指南

4. 服务端是否需要相应的状态码：

建议根据不同的语义，选择HTTP状态码，如果不够，可以自定义一部分状态码

5. 状态码位置：

建议以HTTP状态码的方式返回

这篇关于api设计 - 关于 RESTful API 的设计的几点疑问？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！