关于http api 接口设计的信息

本篇文章给大家谈谈http api 接口设计，以及对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享http api 接口设计的知识，其中也会对进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、http的api接口需要设计哪些东西
• 2、怎么写api接口
• 3、Django REST framework框架之GET, POST, PUT, PATCH, DELETE等API请求接口设计
• 4、如何设计API接口，请求接口时需要进行身份验证，防止第三方随意调用接口？
• 5、开放平台API接口安全性设计——微信支付为例
• 6、API 设计规范

http的api接口需要设计哪些东西

：java发一个http请求过去，带上参数就可以了啊，跟我们在浏览器上访问资源是一样的 只是它返回的是json格式的数据而已 给你两个方法吧： public static String do_post(String url, List name_value_pair)

怎么写api接口

一些刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

推荐使用的是docway 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

GET

用于获取数据

POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

DELETE

用于删除数据

其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描述的请求体的数据类型。

常用的content-type：

application/x-www-form-urlencoded

请求参数使用“”符号连接。

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：

二、响应参数

1. 响应 HTTP Body

响应body同请求body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。

三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

推荐使用的是http://docway.net（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

Django REST framework框架之GET, POST, PUT, PATCH, DELETE等API请求接口设计

一、API接口功能需求http api 接口设计：设计一些接口URL，让前端/客户请求这个URL去获取数据并显示，更改数据（增删改查），达到前后端分离的效果

二、设计逻辑http api 接口设计：通过http协议请求方式GET、POST、PUT、PATCH、DELETE设计符合RESTful规范的api接口也就是URL

三、简易源码：

3.序列化serializers
#导入模型类和rest_framework序列化模块serializers
from .models import Article
from rest_framework import serializers

#定义序列化类，使用继承ModelSerializer方法
class ArticleSerializer(serializers.ModelSerializer):
class Meta:
model = Article #指定序列化的模型类
fields = '_ all _' #选取序列化字段，此处可自行选取字段

4.视图函数views
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from .models import Article
from .serializers import ArticleSerializer
from rest_framework.renderers import JSONRenderer
from rest_framework.parsers import JSONParser
#调用csrf装饰器csrf_exempt模块，解决跨域访问问题
#JSONRenderer它将Python的dict转换为JSON返回给客户端
#JSONParser 负责将请求接收的JSON数据转换为dict

#写法一
#在需要跨域的视图上调用装饰器@csrf_exempt
@csrf_exempt
def article_list(request):
if request.method == 'GET':
arts = Article.objects.all() #获取模型类数据
ser = ArticleSerializer(instance=arts,many=True) #序列化数据instance
#下一步用rest_framework方法里的JSONRenderer方法渲染数据
json_data = JSONRenderer().render(ser.data)
return HttpResponse(json_data,content_type='application/json',status=200)

#写法二
class JSONResponse(HttpResponse):
def _ init (self,data,**kwargs):
content = JSONRenderer().render(data)
kwargs['content_type'] = 'application/json'
super(JSONResponse, self)._ init (content,**kwargs)

#根据id进行增删改操作接口
@csrf_exempt
def article_detail(request,id):
try:
art = Article.objects.get(id=id)
except Article.DoesNotExist as e:
return HttpResponse(status=404)

备注：
*写法二中定义JSONResponse类将返回的数据data与content_type返回类型做了封装
*API接口
GET/POST
api/articles
GET/PUT/PATCH/DELETE
api/articles/1
*Postman测试效果图

如何设计API接口，请求接口时需要进行身份验证，防止第三方随意调用接口？

1. 设定一个密钥比如key = ‘2323dsfadfewrasa3434'。
2. 这个key 只有发送方和接收方知道。
3. 调用时http api 接口设计，发送方，组合各个参数用密钥 key按照一定http api 接口设计的规则(各种排序，MD5，ip等)生成一个access_key。一起post提交到API接口。
4. 接收方拿到post过来http api 接口设计的参数以及这个access_key。也和发送一样，用密钥key 对各个参数进行一样的规则(各种排序，MD5，ip等)也生成一个access_key2。
5. 对比access_key 和access_key2 。一样。则允许操作，不一样，报错返回或者加入黑名单。

开放平台API接口安全性设计——微信支付为例

API接口http api 接口设计，类似 http://mypay.com/refund/order_id=123mch_id=123 ，这个请求我以商户mch_id=123的身份给订单号为order_id=123退款，如果服务器不辩别请求发起者的身份直接做相应的操作，那是及其危险的。

一般的，在PC端，我们是通过加密的cookie来做会员的辨识和维持会话的http api 接口设计；但是cookie是属于浏览器的本地存储功能。APP端不能用，所以我们得通过token参数来辨识会员；而这个token该如何处理呢？
延伸开来，接口的安全性主要围绕Token、Timestamp和Sign三个机制展开设计，保证接口的数据不会被篡改和重复调用。

一般来说，在前端对数据做加密或者前面，是不现实的。前后端使用HTTP协议进行交互的时候，由于HTTP报文为明文，所以通常情况下对于比较敏感的信息可以通过在前端加密，然后在后端解密实现"混淆"的效果，避免在传输过程中敏感信息的泄露（如，密码，证件信息等）。不过前端加密只能保证传输过程中信息是‘混淆’过的，对于高手来说，打个debugger，照样可以获取到数据，并不安全，所谓的前端加密只是稍微增加http api 接口设计了攻击者的成本，并不能保证真正的安全。即使你说在前端做了RSA公钥加密，也很有可能被高手获取到公钥，并使用该公钥加密数据后发给服务端，所以务必认为前端的数据是不可靠的，服务端要加以辩别。敏感信息建议上https。

所以一般建议上https，敏感信息md5混淆，前端不传输金额字段，而是传递商品id，后端取商品id对应的金额，将金额等参数加签名发送到支付系统。金额可以是明文的。

token授权机制 http api 接口设计：用户使用用户名密码登录后，后台给客户端返回一个token（通常是UUID），并将Token-UserId键值对存储在redis中，以后客户端每次请求带上token，服务端获取到对应的UserId进行操作。如果Token不存在，说明请求无效。
弊端 ：token可以被抓包获取，无法预防MITM中间人攻击

用户每次请求都带上当前时间的时间戳timestamp，服务器收到请求后对比时间差，超过一定时长（如5分钟），则认为请求失效。时间戳超时机制是防御DOS攻击的有效手段。

将token，timestamp等其他参数以字典序排序，再加上一个客户端私密的唯一id（这种一般做在服务端，前端无法安全保存这个id）或使用私钥签名，将前面的字符串做MD5等加密，作为sign参数传递给服务端。

地球上最重要的加密算法：非对称加密的RSA算法。公钥加密的数据，可以用私钥解密；私钥签名（加密）的数据，可以用公钥验签。

RSA原理是对极大整数做因数分解，以下摘自维基百科。

暂时比较忙没时间，将于7月29日晚更新。
来更新啦。
微信支付安全规范，可以查看官方文档 https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_3
第1点中，其签名算法最重要的一步，是在最后拼接了商户私密的API密钥，然后通过md5生成签名，这时即使金额是明文也是安全的，如果有人获取并修改了金额，但是签名字段他是无法伪造的，因为他无法知道商户的API密钥。当然，除了微信支付的拼接API生成签名的方法，我们也可以通过java自带的security包进行私钥签名。其中nonce随机字符串，微信支付应该做了校验，可以防止重放攻击，保证一次请求有效，如果nonce在微信支付那边已经存在，说明该请求已执行过，拒绝执行该请求。

阮一峰老师的博客-RSA算法原理： http://www.ruanyifeng.com/blog/2013/07/rsa_algorithm_part_two.html
维基百科： https://zh.wikipedia.org/wiki/RSA%E5%8A%A0%E5%AF%86%E6%BC%94%E7%AE%97%E6%B3%95

API 设计规范

设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让我们能更关注在一些更大的更困难的问题上。

请求和响应将解决一个特定的资源或集合。使用路径（path）来表明身份，body来传输内容（content）还有头信息（header）来传递元数据（metadata）。查询参数同样可以用来传递头信息的内容，但头信息是首选，因为他们更灵活、更能传达不同的信息。

所有的访问API行为，都需要用TLS通过安全连接来访问。没有必要搞清或解释什么情况需要TLS 什么情况不需要TLS，直接强制任何访问都要通过 TLS。

理想状态下，通过拒绝所有非TLS请求，不响应http或80端口的请求以避免任何不安全的数据交换。如果现实情况中无法这样做，可以返回403 Forbidden响应。

把非TLS的请求重定向(Redirect)至TLS连接是不明智的，这种含混/不好的客户端行为不会带来明显好处。依赖于重定向的客户端访问不仅会导致双倍的服务器负载，还会使 TLS 加密失去意义，因为在首次非TLS调用时，敏感信息就已经暴露出去了。

制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。

为了避免API的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。

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

在所有返回的响应中包含ETag头信息，用来标识资源的版本。这让用户对资源进行缓存处理成为可能，在后续的访问请求中把If-None-Match头信息设置为之前得到的ETag值，就可以侦测到已缓存的资源是否需要更新。

为每一个请求响应包含一个Request-Id头，并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能为我们提供一种机制来跟踪、诊断和调试请求。

一个大的响应应该通过多个请求使用Range头信息来拆分，并指定如何取得。详细的请求和响应的头信息（header），状态码(status code)，范围(limit)，排序(ordering)和迭代(iteration)等，参考 Heroku PlatformAPI discussion of Ranges .

在 PUT/PATCH/POST 请求的正文（request bodies）中使用JSON格式数据，而不是使用form 表单形式的数据。这与我们使用JSON格式返回请求相对应，例如:

资源名 （Resource names）:使用复数形式为资源命名，除非这个资源在系统中是单例的 (例如，在大多数系统中，给定的用户帐户只有一个)。 这种方式保持了特定资源的统一性。

行为 （Actions）:好的末尾不需要为资源指定特殊的行为，但在特殊情况下，为某些资源指定行为却是必要的。为了描述清楚，在行为前加上一个标准的actions：

例如：

为了和域名命名规则保持一致，使用小写字母并用 - 分割路径名字，例如:

属性也使用小写字母，但是属性名要用下划线 _ 分割，以便在Javascript****中省略引号。例如：

在某些情况下，让用户提供ID去定位资源是不方便的。例如，一个用户想取得他在Heroku平台app信息，但是这个app的唯一标识是UUID。这种情况下，你应该支持接口通过名字和ID都能访问，例如:

不要只接受使用名字而放弃了使用id。

在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:

推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中，dyno属于app，app属于org可以表示为：

为每一次的响应返回合适的HTTP状态码。好的响应应该使用如下的状态码:

200: GET请求成功，及DELETE或PATCH同步请求完成，或者PUT同步更新一个已存在的资源;

201: POST同步请求完成，或者PUT同步创建一个新的资源;

202: POST，PUT，DELETE，或PATCH请求接收，将被异步处理;

206: GET 请求成功，但是只返回一部分;

使用身份认证（authentication）和授权（authorization）错误码时需要注意：

401 Unauthorized: 用户未认证，请求失败;

403 Forbidden: 用户无权限访问该资源，请求失败;

当用户请求错误时，提供合适的状态码可以提供额外的信息：

422 Unprocessable Entity: 请求被服务器正确解析，但是包含无效字段;

429 Too Many Requests: 因为访问频繁，你已经被限制访问，稍后重试;

500 Internal Server Error: 服务器错误，确认状态并报告问题.

对于用户错误和服务器错误情况状态码，参考： ** **HTTP response code spec

提供全部可显现的资源表述 (例如：这个对象的所有属性) ，当响应码为200或是201时返回所有可用资源，包含 PUT/PATCH和 DELETE 请求，例如:

当请求状态码为202时，不返回所有可用资源，例如：

在默认情况给每一个资源一个id属性。除非有更好的理由，否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的id。

生成小写的UUID格式 8-4-4-4-12，例如：

为资源提供默认的创建时间 created_at 和更新时间 updated_at，例如:

有些资源不需要使用时间戳那么就忽略这两个字段。

仅接受和返回UTC格式的时间。ISO8601格式的数据，例如:

使用嵌套对象序列化外键关联，例如:

而不是像这样:

这种方式尽可能的把相关联的资源信息内联在一起，而不用改变资源的结构，或者引入更多的顶层字段，例如:

响应错误的时，生成统一的、结构化的错误信息。包含一个机器可读的错误 id，一个人类可读的错误信息（message），根据情况可以添加一个url来告诉客户端关于这个错误的更多信息以及如何去解决它，例如:

文档化错误信息格式，以及客户端可能遇到的错误信息id。

客户端的访问速度限制可以维护服务器的良好状态，保证为其他客户端请求提供高性的服务。你可以使用 token bucket algorithm 技术量化请求限制。

为每一个带有RateLimit-Remaining响应头的请求，返回预留的请求tokens。

请求中多余的空格会增加响应大小，而且现在很多的HTTP客户端都会自己输出可读格式（"prettify"）的JSON。所以最好保证响应JSON最小化，例如：

而不是这样：

你可以提供可选的方式为客户端提供更详细可读的响应，使用查询参数（例如：?pretty=true）或者通过Accept头信息参数（例如：Accept:application/vnd.heroku+json;version=3; indent=4;）。

提供一个机器可读的模式来恰当的表现你的API。使用 prmd 管理你的模式，并且确保用prmd verify验证是有效的。

提供人类可读的文档让客户端开发人员可以理解你的API。

如果你用prmd创建了一个概要并且按上述要求描述，你可以为所有节点很容易的使用prmd doc生成Markdown文档。

除了节点信息，提供一个API概述信息:

提供可执行的示例让用户可以直接在终端里面看到API的调用情况，最大程度的让这些示例可以简单的使用，以减少用户尝试使用API的工作量。例如:

如果你使用 prmd 生成Markdown文档，每个节点都会自动获取一些示例。

描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性，例如：加上原型版（prototype）/开发版（development）/产品版（production）等标记。

更多关于可能的稳定性和改变管理的方式，查看 ** **Heroku API compatibility policy

一旦你的API宣布产品正式版本及稳定版本时，不要在当前API版本中做一些不兼容的改变。如果你需要，请创建一个新的版本的API。

关于http api 接口设计和的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 http api 接口设计的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于、http api 接口设计的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。