精华内容
下载资源
问答
  • 使用jupyter notebook快速的搭建分析环境 分析服务器API接口调用数据 根据数据特征进行数据筛选和数据类型转换 对真实爬虫抓取的不规范数据进行清洗和筛选
  • 概述这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考。规范是死的,人是活的,希望自己定的规范,不要被打脸。路由命名规范请求方式请求参数Queryurl?后面的参数,存放请求接口的参数数据。Header请求头...

    概述

    这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考。

    规范是死的,人是活的,希望自己定的规范,不要被打脸。

    路由命名规范

    80072ca8ecec59e726e0cd7ab4ef0188.png

    请求方式

    5e81825600037f3f5573a5eb04b209e9.png

    请求参数

    Query

    url?后面的参数,存放请求接口的参数数据。

    Header

    请求头,存放公共参数、requestId、token、加密字段等。

    Body

    Body 体,存放请求接口的参数数据。

    公共参数

    APP 端请求

    0abfca57514f78e168df72f3f41c2523.png

    WEB 端请求

    3cda968f45dd9fb07558ee9f425a80df.png

    调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用)。

    安全规范

    敏感参数加密处理

    登录密码、支付密码,需加密后传输,建议使用非对称加密

    其他规范

    • 参数命名规范 建议使用驼峰命名,首字母小写。
    • requestId 建议携带唯一标示追踪问题。

    返回参数

    fec5beaa0539caeae5d05d2ed08cc65e.png

    若有分页数据返回的,格式如下

    {
        "code": 1,
        "showMsg": "success",
        "errorMsg": "",
        "data": {
            "list": [],
            "pagination": {
                "total": 100,
                "currentPage": 1,
                "prePageCount": 10
            }
        }
    }

    安全规范

    敏感数据脱敏处理

    用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。

    其他规范

    • 属性名命名时,建议使用驼峰命名,首字母小写。
    • 属性值为空时,严格按类型返回默认值。
    • 金额类型/时间日期类型的属性值,如果仅用来显示,建议后端返回可以显示的字符串。
    • 业务逻辑的状态码和对应的文案,建议后端两者都返回。
    • 调用方不需要的属性,不要返回。

    签名设计

    签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密非对称加密单向散列加密 等,分享下原来写的签名验证,供参考。

    • Go 签名验证
    • PHP 签名验证日志平台设计

    日志平台有利于故障定位和日志统计分析。

    日志平台的搭建可以使用的是 ELK 组件,使用 Logstash 进行收集日志文件,使用 Elasticsearch 引擎进行搜索分析,最终在 Kibana 平台展示出来。

    幂等性设计

    我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。

    举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?

    解决这类问题有 2 种方案:

    一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。

    二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。

    对于第二种方案,就需要服务方的接口支持幂等性。

    大致设计思路是这样的:

    1. 调用接口前,先获取一个全局唯一的令牌(Token)
    2. 调用接口时,将 Token 放到 Header 头中
    3. 解析 Header 头,验证是否为有效 Token,无效直接返回失败
    4. 完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间
    5. 重试时不要重新获取 Token,用要上次的 Token

    小结

    限流设计、熔断设计、降级设计,这些就不多说了,因为大部分都用不到,当用上了基本上也都在网关中加这些功能。

    暂时就想到这么多,规范这东西不是一成不变的,发现有不妥的及时调整吧。

    你们接口的输入输出 Key,命名是用驼峰还是下划线?欢迎留言。

    推荐阅读

    • 一线技术管理者究竟在管什么事?
    • 一个人被提拔,不仅仅是能力,而是信任
    展开全文
  • API接口签名规范

    千次阅读 2018-12-11 11:08:55
    背景:为了增加接口参数安全,对接口参数加盐进行签名校验。 原理:客户端对传送的参数字典排序后,进行md5签名。服务器接收参数后,同理进行参数字典排序后md5签名。若客户端与服务端的签名一致,说明参数未被篡改...

    背景:为了增加接口参数安全,对接口参数加盐进行签名校验。

    原理:客户端对传送的参数字典排序后,进行md5签名。服务器接收参数后,同理进行参数字典排序后md5签名。若客户端与服务端的签名一致,说明参数未被篡改,校验通过。

    请求参数示例:

    字段 数据 类型 描述
    phone 158112341234 String 手机号
    timestamp 1538990392850 long 时间戳
    deviceId mo-231odvepqd String 设备id
    sign 158112341234 String 接口签名,md5(参数字典排序后加盐)

    注:
    1.参数排序时,不包括sign参数
    2.加盐参数使用desKey,放在参数字典排序后的开头位置
    3.遇到数值拼接时,需统一转换成字符串类型。如:123 需转换成 “123”
    4.为避免客户端和服务器端签名对null处理不一致,若参数值为null时,请转换成空字符串("")

    签名步骤
    1.字段字典排序:
    deviceId phone timestamp
    2.参数拼接:
    mo-231odvepqd1581123412341538990392850

    3.加盐:
    hechaojie.commo-231odvepqd1581123412341538990392850

    这里加盐参数为:hechaojie.com,请注意安全存储。

    4.md5签名:
    21bf08491dbf4013a8e9275f1d603e4a

    客户端发送数据示例:

    {"phone":"158112341234","sign":"21bf08491dbf4013a8e9275f1d603e4a","deviceId":"mo-231odvepqd","timestamp":1538990392850}
    

    服务器签名工具类示例:

    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.List;
    import java.util.Map;
    import com.alibaba.fastjson.JSONObject;
    import cn.hechaojie.common.core.encryption.MD5;
    import cn.hechaojie.common.core.util.Constant;
    /**
     * 接口签名工具类
     * @author hecj
     *
     */
    public class SignKit {
         
        // 签名字段
        final static String SIGN_FIELD = "sign";
        /**
         * 签名
         * @param signObj
         * @return
         */
        @SuppressWarnings({ "unchecked", "rawtypes" })
        public static String sign(Object obj) {
            if(obj instanceof Map) {
                return MD5.md5crypt(getDictStr((Map)obj));
            }
            if(obj instanceof JSONObject) {
                return MD5.md5crypt(getDictStr((JSONObject)obj));
            }
            throw new RuntimeException("暂时不支持此类型生成签名,"+obj.getClass());
        }
         
        /**
        * JSONObject字段排序拼接
        */
        public static String getDictStr(JSONObject obj) {
            List<String> keys = new ArrayList<String>(obj.keySet());
            keys.remove(SIGN_FIELD);
            Collections.sort(keys);
            StringBuffer str = new StringBuffer(Constant.ApiDesKey);
            for(String key : keys) {
                Object value = obj.get(key);
                if(value == null) {
                    value = "";
                }
                str.append(String.valueOf(value));
            }
            return str.toString();
        }
         
        public static String getDictStr(Map<String,Object> obj) {
            List<String> keys = new ArrayList<String>(obj.keySet());
            keys.remove(SIGN_FIELD);
            Collections.sort(keys);
            StringBuffer str = new StringBuffer(Constant.ApiDesKey);
            for(String key : keys) {
                Object value = obj.get(key);
                if(value == null) {
                    value = "";
                }
                str.append(String.valueOf(value));
            }
            return str.toString();
        }
    }
    

    注:仅供参考,有更好的方案可@我,共同探讨。

    展开全文
  • Restful API接口规范

    2019-11-20 19:13:12
    REST最大的几个特点为:资源、统一接口、URI和无状态。 请求行为规范 GET(SELECT):从服务器取出资源(一项或多项) POST(CREATE):在服务器新建一个资源 PUT(UPDATE):在服务器更新资源(客户端提供完整...

    REST即Representational State Transfer的缩写,可译为"表现层状态转化”。REST最大的几个特点为:资源统一接口URI无状态

    请求行为规范

    • GET(SELECT):从服务器取出资源(一项或多项)
    • POST(CREATE):在服务器新建一个资源
    • PUT(UPDATE):在服务器更新资源(客户端提供完整资源数据)
    • PATCH(UPDATE):在服务器更新资源(客户端提供需要修改的资源数据)
    • DELETE(DELETE):从服务器删除资源

    响应行为规范

    • 当GET, PUT和PATCH请求成功时,要返回对应的数据,及状态码200,即OK
    • 当POST创建数据成功时,要返回创建的数据,及状态码201,即CREATED
    • 当DELETE删除数据成功时,不返回数据,状态码要返回204,即NO CONTENT
    • 任何时候,如果请求有问题,如校验请求数据时发现错误,要返回状态码 400,即BAD REQUEST
    • 当API 请求需要用户认证时,如果request中的认证信息不正确,要返回状态码 401,即UNAUTHORIZED
    • 当API 请求需要验证用户权限时,如果当前用户无相应权限,要返回状态码 403,即FORBIDDEN
    • 当GET 不到数据时,状态码要返回404,即NOT FOUND
    • 不要忽略了http header中的Content-Type,以json为例,需要在header中添加Content-Type=application/json

    URL规则规范

          示例:http(s)://server.com/app-name/{version}/{domain}/{rest-convention}

                    {version}代表api的版本信息。
                    {domain}是一个你可以用来定义任何技术的区域
                    {rest-convention} 代表这个域(domain)下,约定的rest接口集合

    • URL是区分大小写的,即/Posts和/posts是不同的两个URL,建议使用小写字母
    • URL是区分有无后斜杠,即/posts/和/posts是不同的两个URL,建议以/作为结尾
    • URL应具备良好的可读性,建议使用 "-" 来隔断单词,而不是使用" _"
    • URL应该包含版本信息,即/api/v1/posts/和/api/v2/posts/
    • URL应使用名词而非动词来描述语义

    序列化规范

            Serialization 和 Deserialization即序列化和反序列化。RESTful API以规范统一的格式作为数据的载体,常用的格式为json,确保序列化和反序列化方法的实现,是开发RESTful API最重要的一步准备工作

    数据校验规范

            数据校验是开发健壮RESTful API中另一个重要的一环。仍以json为例,当客户端向服务器发出post, put或patch请求时,通常会同时给服务器发送json格式的相关数据,服务器在做数据处理之前,先做数据校验,是最合理和安全的前后端交互。如果客户端发送的数据不正确或不合理,服务器端经过校验后直接向客户端返回400错误及相应的数据错误信息即可。常见的数据校验包括:

    • 数据类型校验,如字段类型如果是int,那么给字段赋字符串的值则报错
    • 数据格式校验,如邮箱或密码,其赋值必须满足相应的正则表达式,才是正确的输入数据
    • 数据逻辑校验,如数据包含出生日期和年龄两个字段,如果这两个字段的数据不一致,则数据校验失败

    认证权限规范

            常用的认证机制是Basic Auth和OAuth,RESTful API 开发中,除非API非常简单,且没有潜在的安全性问题,否则,认证机制是必须实现的。Basic Auth非常简单,OAuth目前已经成为企业级服务的标配,建议使用OAuth来安全管理数据

     

    HTTP常用状态码说明

    状态码

    状态码英文名称

    中文描述

    200 OK 请求成功。一般用于GET、PUT及PATCH请求
    201 Created 已创建。成功请求并创建了新的资源
    204 No Content 无内容。服务器成功处理,但未返回内容
    400 Bad Request 客户端请求的语法错误,服务器无法理解
    401 Unauthorized 请求要求用户的身份认证
    403 Forbidden 服务器理解请求客户端的请求,但是拒绝执行此请求
    404 Not Found 服务器无法根据客户端的请求找到网页
    405 Method Not Allowed 客户端请求中的方法被禁止
    500 Internal Server Error 服务器内部错误,无法完成请求
    502 Bad Gateway 远端服务器接收到了一个无效的请求
    展开全文
  • APP的数据来源就是API接口,所以API接口对于APP的意义来说不言而喻。 设计API接口最重要的考虑点就是安全机制。 我们这边将从三个方面来考虑怎么设计一个安全的API接口。 防篡改 防篡改就是防止请求的URL参数值发送...

    公众号【国民程序员】回馈粉丝福利: 现金红包和送书活动火热进行中点击参与

    我的新书《Android App开发入门与实战》已于2020年8月由人民邮电出版社出版,欢迎购买。

    书籍详情请见:https://blog.csdn.net/ddnosh/article/details/107666187

    书籍购买地址:京东 当当 天猫

    图片名称

    API接口设计系列文章

    1. Android开发规范:API接口安全设计规范
    2. Android开发规范:API接口通用设计规范


    APP的数据来源就是API接口,所以API接口对于APP的意义来说不言而喻。
    设计API接口最重要的考虑点就是安全机制。
    我们这边将从三个方面来考虑怎么设计一个安全的API接口。

    防篡改

    防篡改就是防止请求的URL参数值发送至服务器的时候被改动。
    普通的API接口格式是xxx.html?key1=xx?key2=xx?key3=xx。
    我们采用 sign 签名方式保证数据传输的正确性。

    我们的app一般会在公司的后台申请一个appKey和appSecret,这两个是一一对应的。
    appKey我们会作为一个参数写在URL中,发送至服务器。
    appSecret则用于参与生成sign的计算。
    sign算法需要足够复杂,最好有一套自己的签名算法,不是外界公开的;
    一般采用安全散列算法实现,比如SHA1。

    sign也要作为一个参数添加到URL中,和appKey一并发送至服务器。
    如:xxx.html?appKey=xx?sign=xx?key1=xx?key2=xx?key3=xx。

    服务器收到请求后,会通过appKey查到对应的appSecret,然后通过同样的散列算法,得到一个sign,然后比较一下两个sign是否相等。如果不相等则数据找到篡改,废弃这条请求。

    另外,关于appSecret有两种使用方式:

    1. appSecret直接写死在客户端代码中,这样直接获取调用即可。
    2. appSecret还可以通过一个专门的接口getSign从后台获取。
      这种情况需要用户首先登录成功后,服务器返回一个accessToken,然后调用appSecret接口需要带上这个accessToken参数。

    防重放

    解决了数据被篡改的问题,还有一个问题就是如果一条正常的请求数据被人获取到了,从而进行二次甚至多次请求怎么办?
    我们这边可以使用nonce + timestamp的解决方案。

    1. nonce
      nonce就是一个随机数,由客户端生成,每次请求将随机数作为一个参数发送给服务器。
      服务器会在数据库里查询是否有这个nonce,如果没有则是一条新的请求,进行正常处理;
      如果能查到已经存在这个nonce,则废弃这条请求。
      nonce可以通过UUID.randomUUID().toString()来生成。
      有个问题就是这个nonce在数据库中随着请求量的增大而导致数据量会越来越大。

    解决这个问题我们可以采用timestamp时间戳的方式。
    2. timestamp
    时间戳是服务器给URL请求设定的一个有限时间范围起点。
    比如服务器认为客户端发送带过来的timestamp与服务器的当前时间戳在10分钟之内,则认为这条请求是有效的。超过了10分钟则废弃这条请求。
    如果10分钟内的请求,需要在数据库中查询nonce是否有记录,如果有记录这废弃这条请求;
    如果没有记录,则记录这个nonce,并且将超过10分钟的nonce全部删除。

    关于这个timestamp获取的问题,同样需要从服务器获取,不然客户端怎么知道服务器的起点计算时间呢?
    上面说到有个获取appSecret的接口,其实我们可以在这个接口中一并将timestamp获取到。

    需要注意的点是,客户端需要在每次发送URL请求的时候,计算一下timestamp的值。
    比如获取到的timestamp=1564588800,那么下次请求的timestamp的值是1564588800 + diffTime。

    服务器收到timestamp后会跟服务器当前时间比对,看是否大于还是小于10分钟。

    一条正常的URL格式就是这样的:

    xxx.html?nonce=xx?timestamp=xx?appKey=xx?sign=xx?key1=xx?key2=xx?key3=xx
    

    所以一个正常的API请求应该是这样的:
    用户登录成功后,每次进行一个API请求,则需要调用一次getSign接口,用于获取appSecret和timestamp。但是肯定不是每次请求都要拉一次这个接口的数据。我们可以在首次请求后,将这些数据保存起来,后续API请求可以直接使用。除非appSecret或者timestamp为空(比如app退出登录后清空appSecret和timestamp)

    Https

    Https是用SSL+HTTP协议构建的可用于网络传输以及身份认证的网络协议;
    http使用明文通信,传输内容可以通过抓包工具截取;
    https自动对数据进行加密压缩,防止监听,防止被抓包看到明文,防中间人劫持。
    苹果从iOS9就开始默认使用https,android9.0开始也强制使用https了,默认阻塞http请求。如果在android9.0中需要兼容http,则需要额外进行特定配置。

    展开全文
  • odoo rest api 服务接口

    2020-05-20 22:01:55
    一、REST_API 是前后端分离最佳实践, 是开发的一套标准或者说是一套规范,不是框架。...odoo oca 已经为这样的接口提供了标准的 api 写法 rest-framework 此时我们则可以规则开发出自己业务所需要的
  • Restful API 接口规范、django-rest-framework框架 问题:什么是API? 答:API接口,提供url. 接口有两个用途: 为别人提供服务,前后端分离。 为什么使用前后端分离? 答:主要为了数据的解耦,提高...
  • 前段时间忙于狐小E中台开发,中台嘛,主要服务于各个轻应用(第三方系统),这时候跟各个轻应用之间的数据交互与传递就在所难免了。那个如何保证数据在传输过程中安全呢?除了https协议之外,能不能加上通用的一套...
  • API接口测试

    2020-12-21 18:17:23
    API: 是应用程序编程接口的缩写,以http协议形式提供,定义了输入输出功能描述的服务接口文档: 用于前后端数据交互沟通使用,小公司是后端自己定义接口文档规矩规范,大公司是架构师定义。接口文档定义了数据的...
  • 接口规范 前后端分离,前后端之间使用 JSON 来交流,两个开发团队之间使用 API 作为契约进行交互。 前后端分离的核心:后台提供数据,前端负责显示。 前提 REST A[I 统一约束客户端和服务器之间的接口。简化和分离...
  • restful 风格 web api规范

    2016-12-02 19:37:00
    api: 标明api接口服务 xxx: 服务 xxx: 资源 版本控制: 一、使用MediaType,即在请求头header中做版本控制,数据格式等控制 想要获取的资源格式 GET /user/123456 HTTP/1.1 Accept: application/vnd....
  • RESTFul API 设计规范

    2020-06-02 16:34:08
    RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。它的大原则容易把握,但是细节不容易做对! ​ URL设计 动词+宾语(名词) 动词覆盖 复数URL 避免多级URL 状态码 ...
  • RESTful接口规范

    2018-11-29 15:16:30
    前后端写接口,需要遵循一个规范,不能想咋样就咋样。 服务器返回的数据尽量是JSON数据格式。 1. 域名 应该尽量将API部署在专用域名之下。 https://api.example.com 如果确定API很简单,不会有进一步扩展,可以考虑...
  • RESTful API 设计规范

    2020-05-13 09:49:00
    一 URL设计 动词+宾语 动词的覆盖 宾语必须是名词 复数 URL 避免多级 URL 二、状态码 状态码必须精确 ...RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。 它的大原则容易把握...
  • 无规矩不成方圆,任何一个软件,如果刚开始没有定义好规范,任由各个开发进行按照自己的喜好进行开发,后面运维的兄弟,估计整天就要骂娘了。...定义多业务接口在后端的服务中,我们的服务只会提供A...
  • Atitit....CGI 应用程序能与浏览器进行交互,还可通过数据库API 与数据库服务器等外部数据源进行通信,从数据库服务器中获取数据。格式化为HTML文档后,发送给浏览器,也可以将从浏览器获得的数据放...
  • 任何应用程序或客户端平台都可以使用API​​规范来实现接口以连接到API或实现北向插件以将其规范桥接到SODA API。 当前,我们支持用于数据管理的关键功能(配置,迁移,文件共享等)的块和文件API。 用于本地实施
  • 前后分离接口规范

    2019-03-22 14:45:00
    1. 开发流程 ...Mock 服务器根据接口文档自动生成 Mock 数据,实现了接口文档即API: 开发流程 2. 具体实施 现在已基本完成了,接口方面的实施: 接口文档服务器:可实现接口变更...
  • 来源:https://www.cnblogs.com/jurendage/p/12653865.html说明:在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的...
  • 在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的一套算法以及规范来保证传输的安全性呢?下面我们就来讨论下...
  • 2、聚合接口:根据调用方需求聚合基础接口数据,业务性强。 1.2 协议 1. 客户端在通过 API 与后端服务通信的过程中, 应该使用 HTTPS(生产环境) 协议 2. 服务端响应的数据格式统一为JSON 1.3域名host prd环境:...
  • 官网提供的API一、调用规范 规范用于指导三方合作伙伴合理调用指数、3天常规预报(24小时)预报服务数据。请求方式:http get接口组成:由固定URL加5个不同的参数组成,完整URL需客户端经过固定方式加密后使用。数据...
  • 数据接口形式

    2019-05-31 09:08:24
    1、非规范 暴露数据库,为用户创建数据库账号,用户直接连接数据库使用... 后端API,启动数据发布服务,用户通过API向服务器提交任务查询拉取数据 后端客户端,使用定制的查询客户端封装后端API(QueryEngine) ...
  • 接口规范 1. 概述

    2018-01-16 15:37:43
    远程管理API提供一组接口,其他系统(如企业的业务管理系统、媒资管理系统、用户管理系统等)可以通过调用接口来查询流媒体服务器的数据和更改流媒体服务器的配置,实现与流媒体服务器的集成。 1.2.适用版本 本文档...
  • 一:token 简介二:timestamp 简介三:sign 简介四:防止重复提交五:使用流程六:示例代码七: ThreadLocal说明:在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢...
  • 2、聚合接口:根据调用方需求聚合基础接口数据,业务性强。1 02 协议 1. 客户端在通过 API 与后端服务通信的过程中, 应该使用 HTTPS(生产环境) 协议2. 服务端响应的数据格式统一为JSON1 03域名hostprd环境:...
  • magic-api是一个基于Java的接口快速开发框架,编写接口将通过magic-api提供的UI界面完成,自动映射为HTTP接口,无需定义Controller,Service,Dao,Mapper,XML,VO等Java对象即可完成常见的HTTP API接口开发 ...
  • 腾讯地图 Webservice API 是基于 HTTP 协议的数据接口,开发者可以使用任何客户端、 服务器和开发语言,按照腾讯地图 Webserice API 规范,按需构建 http 请求,并获取结果 数据(目前支持 json/jsonp 方式返回)。

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 410
精华内容 164
关键字:

数据服务接口api规范