关于api设计:广告推广新动力微吼直播无代码API集成方案

{连贯用户与品牌的新形式} 在电商平台中,视频直播技术正在成为连贯用户与品牌的新形式。通过微吼直播的无代码API集成计划,商家能够轻松地将直播性能集成到本人的平台中,吸引更多顾客,进步用户的购物体验和品牌忠诚度。这种即时的互动形式不仅加强了用户的参与感,也为电商平台带来了更多的转化机会。 {优化客服效率的集成计划} 电商平台的客服零碎是保护顾客关系的重要环节。通过集成微吼直播,客服人员能够通过视频直播与顾客互动,更直观、更高效地展现产品和解答疑难。这种集成无需简单的API对接,大大简化了技术门槛,让客服零碎经营更加顺畅。 {无需API开发的优化策略} 对于电商平台而言,优化经营策略是晋升市场竞争力的要害。将微吼直播集成到电商平台和客服零碎中,能够无需API开发,即刻享受直播带来的各种益处。微吼的无代码集成计划不仅节俭了开发成本和工夫,还为用户提供了更加丰盛的内容和服务。 {简化操作流程的秘诀} 应用微吼直播的另一个劣势是简化了操作流程。商家能够轻松获取相干密钥,而后填入集简云进行受权,即可胜利连贯微吼直播服务。这个过程不须要编写任何代码,也无需深刻理解后端API的具体工作形式。此外,微吼直播还能与电商平台现有的工具无缝集成,实现数据的主动同步。 {集简云:打造无代码开发的连贯} 集简云是一款超级软件连接器,它使得无代码开发的连贯变得更加简略。通过集简云,商家能够轻松买通数百款软件之间的数据连贯,构建自动化与智能化的业务流程。这不仅节俭了大量的人工成本,也进步了工作效率和数据准确性。

February 23, 2024 · 1 min · jiezi

关于api设计:Apikit-自学日记Mock-内置函数

Mock内置函数教程通过编写Javascript脚本设置响应内容,还能够间接应用内置函数设置“申请体触发条件”相干内容,设置的信息等同于在“申请体触发条件”输入框中的设置,如设置Header参数或者申请体参数等,设置实现后,在测试时填写对应的参数进行触发,相干函数应用办法如下: 示例:设置申请体参数,对触发条件进行判断输入符合条件的数值判断触发条件“a”是否等于“eo_test”若等于则输入“胜利”,否则输入“失败” 发动mock测试,当触发条件“a”等于“eo_test”,返回后果返回“胜利” 1.申请地址eo.mock.apiUrl 2.Header 参数eo.mock.headerParam 3.申请体变量[对象:表单/JSON/XML]eo.mock.bodyParseParam 4.申请体变量[文本:Raw]eo.mock.bodyParam 5.Query 参数eo.mock.queryParam 1、申请地址,该办法用于获取API文档中设置的url 通过点击“在测试界面预览”测试后能够看到返回后果,输入API文档中设置的url 2、申请头部参数,该办法用于获取“申请体触发条件” 的申请头部的信息 点击"预览"查看心愿成果 3、申请体变量[对象:表单/JSON/XML],该办法用于获取“申请体触发条件” 表单、JSON、XML格局的申请体 编写实现后能够点击“预览”查看成果 发动mock测试,当触发条件“a”等于“eo_test”,返回后果返回“胜利” 4、申请体变量[文本:Raw],该办法用于获取“申请体触发条件” Raw格局的申请体 编写实现后能够点击“预览”查看成果 5、Query 参数,该办法用于获取“申请体触发条件”Query参数 编写实现后能够点击“预览”查看成果

July 4, 2023 · 1 min · jiezi

关于api设计:Apikit-自学日记发起文档测试RPC

以DUBBO接口为例,进入某个DUBBO协定的API文档详情页,点击文档上方 测试 标签,即可进入 API 测试页,零碎会依据API文档的定义的申请报文主动生成测试界面并且填充测试数据。 对RPC/DUBBO接口发动测试 填写申请报文参数值此测试Demo接口作用是将传入参数名和参数值输入 发送申请查看返回后果填写申请参数值,点击 发送 即可发送申请并查看返回后果。

June 28, 2023 · 1 min · jiezi

关于api设计:集成的-API-调试工具以前没听过

在 Eolink ApiKit之前,定义 API 用 Swagger,生成文档用 YAPI,前端自测用 Mock,接口测试用 Postman,性能测试用 JMeter。 有了 Eolink ApiKit之 之后,Apikit = Postman + Swagger + Mock + JMeter,团队API 治理老本大幅升高。 Apikit 是联合 API 设计、文档治理、自动化测试、监控、研发治理和团队合作的一站式 API 生产平台,从集体开发者到跨国企业用户,Apikit 帮忙寰球超过50万开发者和10万家企业更快、更好且更平安地开发和应用 API。 体验链接:https://www.eolink.com/?utm_source=cpsf&utm_content=cpy106 外围性能1.1 API文档Eolink Apikit反对弱小的API文档治理性能,包含多种创立文档的形式,导入导出,版本治理,查重等。 1.2 API调试当咱们创立好 API 文档之后,能够立即对该 API 进行测试,API 研发治理平台 提供了以下次要个性来帮忙测试人员疾速发动 API 测试: 反对本地测试、局域网测试、在线测试等;反对一键切换测试环境,应用全局变量、减少额定申请参数、扭转申请地址等;反对间接在界面编辑 JSON、XML 申请数据,不再须要手写 JSON、XML 等数据结构;反对将测试数据保留为测试用例,当前能够间接应用测试用例进行测试;反对批量测试 API,比方测试登录接口的多种状况并且返回实时测试数据;反对在测试过程中编写代码进行签名、加解密、生成随机数据等操作; 1.3 Mock API通过 Mock API,您能够当时编写好 API 的数据生成规定,由 Apikit 动静生成 API 的返回数据。开发人员通过拜访 Mock API 来取得页面所须要的数据,实现对接工作。Mock API 反对依据不同的申请参数返回不同的 HTTP Status Code、Header、Body 等数据。您能够在一个 API 文档里创立多个 Mock API ,模仿前端发动的各种申请,不便对前端逻辑进行校验。当我的项目正式公布时,只需将 Mock API 的地址前缀替换为理论的拜访地址即可。 ...

May 23, 2023 · 1 min · jiezi

关于api设计:我总结了一次-API-接口设计原则有这些

联合我多年在 API 行业摸爬滚打的教训,我总结了一下,API 接口设计准则有这几条: 接口设计应该简略易用,易于了解和应用;接口设计应该反对多种格局,如JSON、XML等;接口设计应该反对多种申请形式,如GET、POST等;接口设计应该反对多种版本,以便于前期的扩大和降级;接口设计应该思考安全性,如采纳https协定;接口设计应该思考性能,如采纳缓存技术;接口设计应该思考可扩展性,如采纳分布式架构;接口设计应该思考可维护性,如采纳模块化的形式;接口设计应该思考可测试性,如采纳单元测试的形式。如果你日常会用到 api 管理工具的话,无妨看看我目前参加的这个开源我的项目,Postcat 开源的 API 管理工具,纯国产,收费的,主打插件生态,适宜中小团队以及集体开发者应用,有 API 相干的外围性能。 目前在 Github 上 3k star,如果你感觉这个我的项目还不错的话,无妨点个 star 反对一下~ Github:https://github.com/Postcatlab/postcatDemo:https://postcat.com/zh/?utm_source=sf&utm_campaign=xh&utm_con... Postcat 外围性能:API 文档治理:可视化 API 设计,生成 API 文档API 测试:主动生成测试参数,主动生成测试用例,可视化数据编辑插件拓展:泛滥插件扩大产品性能,打造属于你和团队的 API 开发平台Mock:依据文档主动生成 Mock,或创立自定义 Mock 满足简单场景团队合作:既能实现 API 分享也能能够创立云空间独特合作Postcat 劣势:免登录即可测试:省去繁琐的验证登录的操作界面简洁:没有冗余的性能与简单选项收费:中小团队以及集体应用丰盛的插件:反对数据迁徙(postman\apifox\apipost等)、主题、API 平安等高达 30 款插件国产:能更好的了解国内用户的需要,与开发团队沟通无障碍欠缺的用户文档:跟着操作就能疾速上手

May 10, 2023 · 1 min · jiezi

关于api设计:接口响应错误码应该怎么设计ChatGPT这么说

背景在做接口设计时,对于一些异样的响应如何解决始终是开发者们头疼的问题,不同的团队有不同的规定。有的团队会利用http状态码去示意各种状况的异样。有的团队会针对异样对立的返回200,而后在数据中减少一个code参数,用于示意各种异样的错误码,message参数中示意具体的错误信息。如下图所示:那么到底两种计划有什么区别呢?我试着问了问ChatGPT。 ChatGPT这么说问:在做接口设计时,能够用 http 状态码示意一些异常情况。也能够对立设置 http 状态码为 200,而后在返回的数据中增加自定义的 code 码。这两种形式各有什么劣势和劣势呢?另外请提供一个抉择上的倡议答: 在做接口设计时,能够用 http 状态码示意一些异常情况。也能够对立设置 http 状态码为 200,而后在返回的数据中增加自定义的 code 码。这两种形式各有优劣,具体如下: 应用 http 状态码的长处是合乎 HTTP 协定的标准,能够让客户端和服务器之间更容易地替换信息和处理错误。HTTP 状态码曾经定义了很多常见的状况,比方 200 示意胜利,404 示意找不到资源,500 示意服务器外部谬误等。应用 http 状态码的毛病是有些状况可能不太适宜用规范的状态码来示意,比方业务逻辑上的谬误或者非凡的需要。尽管能够创立自定义的状态码,然而这可能会导致与其余零碎或框架不兼容或者引起混同。应用自定义的 code 码的长处是能够更灵便地示意各种业务逻辑上的谬误或者非凡的需要,比方用户未登录、余额有余、验证码谬误等。应用自定义的 code 码的毛病是不合乎 HTTP 协定的标准,可能会让客户端和服务器之间更难以替换信息和处理错误。比方,如果客户端收到一个 200 的状态码,然而实际上接口返回了一个业务逻辑上的谬误,那么客户端就须要解析返回数据中的 code 码来判断是否胜利,并且依据不同的 code 码做出相应的解决。综上所述,在抉择应用 http 状态码还是自定义 code 码时,须要思考以下几个因素: 是否须要恪守 HTTP 协定的标准是否须要与其余零碎或框架兼容是否须要表白非标准或简单的业务逻辑是否须要简化客户端和服务器之间的通信和错误处理一般来说,倡议应用 http 状态码作为次要的响应形式,并且尽量应用规范定义好的状态码。如果有非凡需要或者无奈用标准状态码示意,则能够思考应用自定义 code 码作为补充,并且在文档中分明地阐明每个 code 的含意和对应操作。 不得不说,ChatGPT果然弱小,齐全的解答了笔者的纳闷。总而言之,就是说咱们在设计接口响应时,如果是失常响应,那么就返回200和本来的数据就好了。如果是有异样的状况,则能够status code 和自定义code配合应用。一个最佳的实际倡议是联合两种形式,即应用 HTTP 状态码示意根本的谬误类型和语义,同时在返回数据中增加自定义 code 码示意具体的业务谬误。例如: { "code": 1001, "message": "用户名或明码谬误", "data": null } 这样既能够恪守 HTTP 标准,又能够提供更多的错误信息。既然要恪守HTTP标准,那么咱们就得晓得HTTP标准如何规定咱们怎么定义状态码的,于是我又问了ChatGPT。问:HTTP状态码设置的标准是什么?答: ...

March 9, 2023 · 1 min · jiezi

关于api设计:译文-A-poor-mans-API

作者:Nicolas Fränkel翻译:Sylviahttps://blog.frankel.ch/poor-man-api/在 API 日渐风行的年代,越来越多的非技术人员也心愿能从 API 的应用中获利,而创立一套成熟的 API 计划须要工夫老本和金钱两方面的资源加持。在这个过程中,你须要思考模型、设计、REST 准则等,而不仅仅是编写一行代码。 如何打造一个具备高性价比且能继续迭代的产品,成为越来越多技术团队的指标。本文将展现如何在不编写任何代码的状况下,简略实现一个 API 实际。 计划初试该解决方案次要应用的是 PostgreSQL 数据库,PostgreSQL 是一个开源 SQL 数据库。同时咱们没有编写 REST API,而是应用了 PostgREST 组件。 PostgREST 是一个独立的 Web 服务器,它能够将 PostgreSQL 数据库间接转换为 RESTful API。如果你想理解 PostgREST 的应用办法,能够参考入门指南文档,内容十分全面且开箱即用。 接下来,咱们将它利用到一个简略的示例中。 具体步骤以下过程你能够在 GitHub 上找到残缺源代码。下方展现了一个通过 CRUD API 公开的 product 表。 因为我没有找到任何现成的 Docker 镜像,所以我独自创立了一份新的 Dockerfile。其中次要波及依赖项的装置和参数化数据生成。 Dockerfile FROM debian:bookworm-slim                                                   ARG POSTGREST_VERSION=v10.1.1                                               ARG POSTGREST_FILE=postgrest-$POSTGREST_VERSION-linux-static-x64.tar.xz     RUN mkdir postgrestWORKDIR postgrestADD https://github.com/PostgREST/postgrest/releases/download/$POSTGREST_VERSION/$POSTGREST_FILE \    .                                                                       RUN apt-get update && \    apt-get install -y libpq-dev xz-utils && \    tar xvf $POSTGREST_FILE && \    rm $POSTGREST_FILE之后,Docker 镜像在 /postgrest 文件夹中会蕴含一个名为 postgrest 的可执行文件。这里能够通过 Docker Compose 来部署: docker-compose.yml version: "3"services:  postgrest:    build: ./postgrest                                       volumes:      - ./postgrest/product.conf:/etc/product.conf:ro        ports:      - "3000:3000"    entrypoint: ["/postgrest/postgrest"]                     command: ["/etc/product.conf"]                           depends_on:      - postgres  postgres:    image: postgres:15-alpine    environment:      POSTGRES_PASSWORD: "root"    volumes:      - ./postgres:/docker-entrypoint-initdb.d:ro接下来能够执行以下命令,查问前文提到的 product 表: curl localhost:3000/product失去如下后果反馈: [{"id":1,"name":"Stickers pack","description":"A pack of rad stickers to display on your laptop or wherever you feel like. Show your love for Apache APISIX","price":0.49,"hero":false}, {"id":2,"name":"Lapel pin","description":"With this \"Powered by Apache APISIX\" lapel pin, support your favorite API Gateway and let everybody know about it.","price":1.49,"hero":false}, {"id":3,"name":"Tee-Shirt","description":"The classic geek product! At a conference, at home, at work, this tee-shirt will be your best friend.","price":9.99,"hero":true}]计划优化只管上文提到的这套解决方案无效,但仍存在很大的改良空间。比方数据库用户不能更改数据、实际操作中每个人都能够拜访相干数据等。这对于与产品相干的数据来说,可能不是一个大问题,但如果是医疗数据呢? PostgREST 的官网应用文档中提到了这一点,并明确提出:倡议用户应用反向代理。 提到反向代理,就不得不将眼光转向到 API 网关行列。与 NGINX 不同,这里我选取了开源畛域十分沉闷的 API 网关产品 — Apache APISIX。APISIX 是一个动静、实时、高性能的 API 网关,提供了负载平衡、动静上游、灰度公布、精细化路由、限流限速、服务降级、服务熔断、身份认证、可观测性等数百项性能。 ...

December 2, 2022 · 2 min · jiezi

关于api设计:服务端-统一api-格式

议定的格局如下:{"code":0,"message":"message","data ":"returnData","status":200}字典阐明:status http状态码code 业务码(错误码)message 提示信息data 数据体服务端个别有两种状况返回:以httpStatusCode来标记响应状态,比方2xx,400,500 前端顶层依据状态码解决响应体不应用http状态码,间接以业务码code标记,状态码始终200,。返回响应体:以状态码响应后果状态时,谬误时,依照以上响应体返回,正确间接返回数据体;不论正确与否都依照以上响应体返回;前端辨认格局体的时候,倡议查看存在 code、status 两个字典,以辨别偶合的数据体。

April 18, 2022 · 1 min · jiezi

关于api设计:如何优雅地进行接口管理腾讯阿里资深研发首次分享秘诀

**#### 工夫都去哪里了**麻利迭代和团队合作,前后端拆散的工作模式简直是每个互联网公司的惯例工作模式。 前后端拆散,各自开发的长处很多,其中一项是它只须要提供一个对立的API接口,即可被web,iOS,Android等多个客户端应用,效率大大提高。 但生于麻利,死于迭代,困于团队合作经常是这种软件研发模式的一大弊病。 随着我的项目一直推动、变更,我的项目越来越大,保护老本也越来越高。 因为某些公司接口文档治理形式采纳wiki及html,openapi模式,版本迭代较快,接口经常变更,成员间update和文档保护却经常跟不上。 在API治理方面越到前期越存在着可观且隐形的“人力资源”节约: 1)文档老旧不可用,新人上手工作、相熟我的项目靠“老人”的口口相传,造成人力双重节约,团队成员本人的工作进度碰壁,新人胜任工作的进度缓慢。2)接口因为初期设计问题/性能扩大/需要变更问题而批改,但批改后往往难以及时同步到前端和测试等上游环节3)接口在设计初期不标准,造成前端,测试在调试和测试了解上的艰难,甚至局部接口须要从新返工这些状况越到我的项目倒退前期会越重大。以至于不少研发人员总是埋怨:写代码不累,沟通对接心累;工作不辛苦,就是命苦。如何优雅地进行API治理 为了解决研发人员的问题,咱们须要解决API治理中的各个痛点,换言之,一个完满的API管理工具应满足如下特色: **在接口设计阶段,能标准研发人员的接口设计在接口调试阶段,提供多种性能充沛调试,高度仿真理论工作情境在接口保护过程中,保护成本低,且各项变更能及时update到上游工作环节的团队共事一站式服务,一个工具就可实现接口的设计、调试、保护,测试过程,不须要重复导入导出,各个软件来回切换,提高效率。**最终的解决方案 笔者在网上找了很长时间,发现一款简直能满足以上需要的解决方案软件--Apifox. 这个软件的次要个性: 可视化接口设计界面,反对 https 和 https 协定,遵循openApi和 Json Schema标准,各项http申请参数与接口形容间接填写即可。反对构建数据模型,可供多个申请参数复用。 媲美postman的接口调试性能,除此之外,还反对“零配置”mock高度仿真的业务数据,反对读取数据库 零碎主动生成代码 依据接口及数据数据模型定义,零碎主动生成接口申请代码、前端业务代码及后端业务代码 实时更新云端变更的数据到各个团队成员,防止数据不统一导致的反复工作和返工;代码更新和文档更新在同一软件全副实现,缩小保护工作量 项目管理 为不同的我的项目角色调配不同执行权限,无效爱护我的项目数据安全;反对openapi,postman格局的旧有我的项目导入apifox,实现我的项目无痛迁徙,反对html格局,openapi等多种格局的接口数据导出。接下来笔者再针对一些性能进行具体的介绍 接口设计界面可视化,能够对接口信息进行编辑治理,get,post等惯例的接口申请办法间接下拉框抉择; query,body,header参数间接对应填写,返回参数反对JSON,XML格局导入,并能间接进行格局校验。 接口形容局部反对Markdown格局的文本。 接口调试接口调试有两种模式,一种是不须要创立我的项目的快捷调试,间接校验接口申请 和返回参数, 一种是在我的项目里对单个接口调试, 这部分的性能根本等同于postman。 可增加多种前后置操作:校验返回response,查看返回状态和数据结构是否合乎预期。 接口保护 当变更接口时间接在apifox内批改并生成新代码,同时阐明文档就寄存在同一个地位,棘手批改文档阐明就变得十分不便。接口变更之后,合作成员能及时同步云端变更。项目管理 反对数据导入导出,主动生成接口代码针对不同角色的成员,设置不同的数据权限。如后端研发能够批改接口数据,而前端和测试成员只有只读权限,我的项目外人员则只有访客权限只能查看到接口信息而无奈查看数据类型。 可针对开发调试,测试验证,线上应用配置不同的服务器: 此外 Apifox不仅是一款针对研发人员的API管理工具,还能为测试人员提供接口测试,接口自动化测试,测试治理等一系列性能。能够说是一款研发团队一站式晋升效率的神器。————————————————版权申明:本文为CSDN博主「FishInDesert」的原创文章,遵循CC 4.0 BY-SA版权协定,转载请附上原文出处链接及本申明。原文链接:https://blog.csdn.net/yuexias...

December 17, 2021 · 1 min · jiezi

关于api设计:api平台原理

数据仓库侧作为泛滥数据的汇合,除了提供报表和数据分析以外,还会以各种api的形式向外提供数据服务,供后端各种零碎应用。api平台的实现形式多种多样,开源的api平台也有多种版本,简略梳理一下接口平台的性能和实现形式。 数据生产各种接口的数据都不是凭空来的,api平台的数据源能够简略的分为离线数据和实时数据,离线数据的存储有mysql,postgresql,hive,presto等,这部分的数据大都是有调度零碎通过定时工作写进去。实时的数据存储形式有redis,hbase,ES等,实时的数据大多数是由spark,flink或者其余生产实时音讯队列的零碎写入。尽管从存储上能够简略的依照上述的办法去划分,然而在应用上各种存储的介质提供的数据能力上却没有那么显著的界线,例如对一些实时性能要求没那么高的外部零碎,能够通过presto提供一些近实时的接口。 接口实现无论各种数据源的解决其实都一个逻辑,前端抉择数据源,写入须要的sql,sql中能够抉择对应表字段的子集,sql的限度局部能够用变量去标识,变量通过前端传入,后端的adpter拿到sql当前去将变量替换成要替换的值即可。对不同的数据源初始化不同的client去查问数据,将查问到的后果通过分页,纯文本等形式返回。存储在mysql,postgresql中的数据个别是一些离线数据,这部分数据应用方会每天定时的拉取,数据到应用方后做缓存解决,接着再去应用,同时对小数据集会提供实时查问,在须要的字段上加上索引即可。hive中的数据个别有两种解决逻辑,第一是将hive数据同步到mysql和postgresql中,通过mysql和postgresql向外提供数据,第二是通过presto查问引擎去查问数据,presto的这种形式适宜低频的离线批次查问,高频查问会受到presto集群的影响,在查问顶峰时段接口会超时。对上述的一部分key value类型的接口数据,提供了redis查问的性能,接口零碎会有定时工作将数据刷进redis中,查问的时候间接走redis查问。 数据应用提供http和dubbo的形式供调用方拉取数据。离线局部的数据数据产出当前,定时工作会发消息进来,应用方可通过承受到的零碎来拉取数据。 权限治理对窃密级别高的接口做了权限的限度,只有特定的内网ip能够拜访。同时整个零碎还有一层白名单和黑名单的限度,治理所有接口的权限。

August 2, 2021 · 1 min · jiezi

关于api设计:选择API管理平台之前要考虑的5个因素

API(应用程序编程接口)经济的飞速增长导致对API治理平台的需要相应减少。 这些解决方案可在整个生命周期内帮忙创立,施行,监控,剖析,爱护和治理API。 据一些预计,寰球API治理市场预计在2018年至2023年的预测期内将以每年32.9%的速度增长,到2023年价值将从2018年的12亿美元增长至51亿美元。 因为API治理的重要性正在回升,许多提供商已开始提供这些服务。因而,在抉择适宜您须要的解决方案之前,必须做功课。 在本文中,我将探讨以下五个重要因素,以便抉择一个用于治理外部API和内部API订阅的平台: 使用方便可管理性治理平安宽度让我更具体地解决这些问题。 1.易于应用 在寻找API管理工具时,易用性应该是次要思考因素,尤其是在可能须要管制和治理多个API的企业环境中。 如果您评估应用该解决方案启动和运行有如许容易,这将有所帮忙。无论采纳哪种部署办法(例如云或本地部署),都应确保所选工具的安装简单。提供者是否提供反对,教程或其余资源以使平台易于部署? 此外,您应该评估平台性能的易用性。例如,开发人员执行搜寻以发现API容易吗?它是否提供对代码段的反对,以便将API轻松集成到应用程序中? 是否有一个直观的仪表板,能够为团队应用的所有API提供剖析和疾速见解?该平台是否容许管理员轻松地治理一组开发人员? 此外,能够依据您的组织的品牌轻松自定义平台,这是您寻求的一项杰出性能。它能够帮忙您的API程序怀才不遇,并丰盛您的企业品牌形象。 2.可管理性 大多数企业具备多样化的开发,测试和生产环境。例如,企业可能具备应用各种技术,天文上扩散的开发人员团队或横跨寰球数据中心的部署环境创立的不同类型的API。 因而,可管理性将是抉择决定之前的重要因素。借助杰出的API管理工具,您能够取得集中的平台来治理各种环境之间的抵触,并充分利用您的API。 您须要一个无效的解决方案,该解决方案将充当单个组织范畴内的核心,以便从一个地位治理您的API。这样,您将防止资源重复,并确保各种技术的顺利集成。 您应该思考的一些因素包含解决各种团队治理流动的效率,例如在团队中增加或删除用户,依据性能或用例的相似性从多个环境中整顿API的能力以及用于治理API应用状况的报告工具的可用性。 3.治理 治理是一个总体术语,通常用于指代宽泛的API治理,监控和可见性要求。它规定了向各种使用者公开API数据和性能的条款和条件。 正确的API治理解决方案应该使您可能简化和管制API的采纳,而不论组织的规模如何。它应该容许您编写策略,使组织外部和内部的不同角色能够完满地拜访API。 您应该在API解决方案中寻找的一些包含以下根本治理的性能:强制执行拜访治理以避免未经受权的入侵;执行审计跟踪以跟踪歹意应用模式;进行剖析和监控以与API性能放弃同步。 一个好的平台还能够让您理解API应用状况,并通过将API列入黑名单或白名单来管制采纳状况。 4.安全性 抉择API治理平台时,安全性是另一个至关重要的思考因素。随着API的宽泛采纳,黑客仿佛将注意力从传统的指标转移到了尚未被详尽利用的新畛域:API。 因为API提供了对数据和服务的编程拜访,因而API文档提供了这种高度通明的反对,使其成为歹意利用的软指标。 实际上,驰名的钻研和征询公司Gartner预测,到2022年,API破绽将是大多数企业Web零碎中蒙受的攻打次数最多的起因。 因而,在抉择API治理提供程序时,不应将安全性放在首位。例如,您能够评估平台是否容许您利用弱小的身份验证和受权措施来爱护对API程序的拜访。 5.广度 最初,您应该思考平台性能的广度;也就是说,它的全面水平。它涵盖了从开发到部署的整个API生命周期胜利的所有根本方面吗?这些方面包含两个阶段-API使用者和API发布者。 对于API使用者,您应该评估该工具是否解决了以下方面:API的开发,集成,监控和治理。 另一方面,对于API发布者,API治理服务应解决以下方面:API的设计,创立,测试,安全性和治理。 有了一个全面的API治理平台,该平台能够解决大部分残缺的API生命周期治理模型,则能够实现API程序最后构想的收益。 论断 您可能曾经意识到,抉择API治理提供程序并不容易。因而,花点工夫对平台进行适当评估并确保其满足您的需要和偏好至关重要。 翻译:https://datayi.cn/w/noqw7LdR

November 1, 2020 · 1 min · jiezi

开放API网关实践三-限流

如何设计实现一个轻量的开放API网关之限流文章地址: https://blog.piaoruiqing.com/blog/2019/08/26/开放api网关实践三-限流/ 前言开发高并发系统时有多重系统保护手段, 如缓存、限流、降级等. 在网关层, 限流的应用比较广泛. 很多情况下我们可以认为网关上的限流与业务没有很强的关联(与系统的承载能力有关), 且各个子系统都有限流这种需求, 将部分限流功能放到网关会比较合适. 什么是限流众所周知, 服务器、网站应用的处理能力是有上限的, 不论配置有多高总会有一个极限, 超过极限如果放任继续接收请求, 可能会发生不可控的后果. 举个栗子????, 节假日网上购票, 常常会遇到排队中、系统繁忙请稍后再试等提示, 这便是服务端对单位时间处理请求的数量进行了限制, 超出限制就会排队、降级甚至拒绝服务, 否则如果把系统搞崩了, 大家都买不到票了╮( ̄▽ ̄)╭. 我们先给出限流的定义: 限流是高并发系统保护保护手段之一, 在网关层的应用很广泛. 其目的是对并发请求进行限速或限制一个时间窗口内请求的数量, 一旦达到阈值就排队等待或降级甚至拒绝服务. 其最终目的是: 在扛不住过高并发的情况下做到有损服务而不是不服务. 常用限流玩法令牌桶令牌桶算法, 是一个存放固定数量令牌的桶按照固定速率添加令牌. 如图: 按照固定速率向桶中添加令牌.桶满时拒绝增加新令牌.每次请求消耗一个令牌(也可根据数据包大小来消耗对应的令牌数).当令牌不足时, 拒绝请求(或等待).特点: 可以应对一定程度的突发.举个现实生活中比较常见的例子来理解, 电影院售票, 每场电影所售出的票数是一定的, 如果来晚了(后面的请求)就没票了, 要么等待下一场(等待新的令牌发放), 要么不看了(被拒绝). 漏桶漏桶是一个底部破洞的桶, 水可以匀速流出(这时候不考虑压强, 不要杠( ̄. ̄)), 所以与令牌桶不一样的是, 漏桶算法是匀速消费, 可以用来进行流量整形和流量控制. 如图: 固定容量的漏桶, 按照固定速率流出水(不要杠水深和压强的问题).流入水的速率固定, 溢出则被丢弃.特点: 平滑处理速率.[版权声明]本文发布于朴瑞卿的博客, 允许非商业用途转载, 但转载必须保留原作者朴瑞卿 及链接:blog.piaoruiqing.com. 如有授权方面的协商或合作, 请联系邮箱: piaoruiqing@gmail.com. 应用级限流一个单体的应用程序有其承受极限, 在高并发情况下, 有必要进行过载保护, 以防过多的请求将系统弄崩. 最简单粗暴的方式就是使用计数器进行控制, 处理请求时+1, 处理完毕后-1, 除此之外我们还可以利用前文提到的令牌桶和漏桶来进行更精细的限流.如果网关是单体应用, 我们完全可以不借助其他介质, 直接在应用级别进行限流. ...

October 7, 2019 · 1 min · jiezi

对API进行版本控制的重要性和实现方式

我在API设计中收到的最常见问题之一就是如何对API进行版本控制。虽然并非所有API都完全相同,但我发现在API版本控制方面,某些模式和实践适用于大多数团队。我已经将这些内容收集起来,下面将提供一些关于版本控制策略的建议,该策略将帮助大多数API提供商,无论他们是向内部署API,还是对外的API。 API版本真的那么重要吗?API是你与API使用者之间建立的纽带。正常情况下,你们之间的纽带不会轻易的断开。纽带包括URI模式,有效负载结构,字段和参数名称,预期行为以及其他内容。这种方法的最大好处是显而易见的:API使用者的理解不会变更,应用程序可以保证持续有效。 但是,永久不变是不现实的。有时因为业务变化,你可能需要对API进行重大改变。发生这种情况时,最好的方式是,你确保不会做任何会导致API使用者修复代码的事情。 打破与不间断的变化非破坏性变更往往就像是“添加剂”,一般是添加新字段或嵌套资源到资源陈述,又或是增加新的端点,如PUT或PATCH。API使用者从一开始应该构建能够适应这些非破坏性更改的客户端代码。 突破性变化包括:1.名字段或资源路径,通常在API发布后为了统一命名规范。 2.更改有效负载结构,一般是适应以下内容: a.重命名或删除字段b.将字段从单个值更改为一对多关系(比如从一个帐户的一个电子邮件地址移动到这个帐户的电子邮件地址列表)c.修改了API的URL,导致返回结果不一致的情况。简而言之,一旦你将API对外公开发布,你就必须保持它是可用的并且不会影响到使用者的。如果您遇到多个项目,则需要对API进行版本控制,以防止破坏现有的API使用者。 定义API版本策略任何不断发展变化的API都需要API版本控制策略。你的API版本可以适应根据API使用者的期望而切换不同版本变得有所不同。我通常建议将以下API版本控制策略作为整体API管理系统的一部分。 1.如果你的API处于早期测试版本中,为了获得消费者的反馈,请建立您的API可能会发生变化的正确期望。在此阶段内,你会保留这个版本一段时间,因为你的API设计可能还会更改。作为消费者,API是不稳定的,因此他们应该预期到可能会发生的变化。 2.一旦发布,你的API应被视为契约,如果没有新版本,则不能被替换。 3.不间断的更改会导致次要版本出现问题,客户端会自动迁移到最新版本,不会出现任何负面副作用。 4.突破性的变化意味着客户必须迁移到此新版本,因为它包含一个或多个重大更改。你必须与API使用者建立适当的时间表并定期沟通,以确保他们能方便地迁移到新版本。但在某些情况下,这可能无法马上实现,所以你的团队将会被要求暂时性支持以前的API版本。 何时必须实现API版本控制一旦确定需要新版本的API,就需要知道如何处理它。实现API版本控制有三种常用方法。 1.资源版本控制 该版本是HTTP请求中Accept标头的一部分,例如,Accept:application/vnd.github.v3+json 发送到GET /customers。这考虑了许多版本控制的首选形式,因为资源在版本化的同时需要保持URI相同。如果未在Accept标头中提供,某些API会选择提供最新版本作为默认版本。 2.URI版本控制 该版本是URI的一部分,作为前缀或后缀,例如,/v1/customers 或/customers/v1。虽然URI版本控制不如基于内容的版本控制那么精确,但它往往是最常见的,因为它适用于不支持自定义标头的各种工具。缺点是资源URI随每个新版本而变化,有些人认为这与拥有永不改变的URI的意图背道而驰。 3.主机名版本控制 该版本是主机名的一部分而不是URI,例如,https://v2.api.myapp.com/cust...。当技术限制阻止基于URI或Accept标头到API的正确后端版本时,将使用此方法。 备注:无论您选择哪个选项,API版本都只应包含主要编号。不需要小数字(即  /v1/customers,不是/v1.1/customers)。 实现版本控制的工具使用工具和技术可以从根本上实现API版本控制过程。用市场上优秀的API编辑器将使技术开发团队能够在更短的时间内生成并切换更多的API版本,从而不断改进设计决策。 结合工具进行版本控制是大多数开发过程的重要组成部分。API设计领域中也有这种能版本控制的工具,实际上,全球范围内API服务领域中已经存在一些优秀的Web API设计工具。 现在,如EOLINKER、RAML、Swagger,都提供了出色的编辑工具来支持他们的语言。EOLINKER采用的是版本对比和重点标注提示,可以清晰的切换、对比。RAML、Swagger采用的是版本切换,方便程度可能略逊一点。而且只有前者是支持中文的,后两种只支持英文语言。这些API编辑器都能轻松地实现API版本的控制,使得更容易在更短的时间内切换运行版本。 附上EOLINKER的官方网址:https://www.eolinker.com 附上Swagger的官方网址:https://swagger.io/ 附上RAML的官方网址:https://raml.org/ 最后的想法请记住,API是与你的消费者链接的枢纽。打破旧的连接,就需要新版本。选择策略,制定计划,并与API使用者沟通该计划,这才是版本控制的最终目的。 参考资料:James Higginbotham,When and How Do You Version Your API? 原文地址:https://dzone.com/articles/wh...

August 7, 2019 · 1 min · jiezi

构建和管理有效API市场的关键步骤

API市场关键要点各个行业的公司正在寻找通过外部API扩展服务来塑造数字业务的方法。然而,要获得API的真正好处,是需要超越基本的API管理,再到创建API市场,这是一种专注于连接生产者和消费者的专用平台业务模型。随着越来越多的公司寻求商业平台以获得竞争优势,API市场将平台业务模型的优势带给了API管理。 API市场通常都会包括以下几个部分:在典型的场景中,生产者首先发布API,然后通过API开发平台对这些API进行编辑和测试运行。API管理系统为任何API市场提供一个完整的规范标准并使其能够有效运行。第一个部分是使用有效的API开发平台。在API市场中,API开发平台必须提供直观的体验。除了使用API开发平台之外,企业还需要在市场中引入促进API重用的激励措施,继续推动API变现货币化。在管理API市场时,企业需要保持对谁可以发布内容和进度的控制,并确保根据既定的规范和标准(如URL模式,命名约定和访问控制规则)发布合符要求的API。因此,API市场通常不仅涉及开发平台和API管理的其他技术方面,还涉及确保API实现其目标的业务和人员方面,尤其是促进API的消费和使用。在以下部分中,我们将探讨在API生态系统中发挥作用的技术和业务考虑因素,并讨论创建和管理有效API市场的关键步骤。 API管理支持API市场API市场通常都会包括以下几个部分;在典型的场景中,生产者首先发布API,然后通过API开发平台对这些API进行编辑和测试运行。使用者可以直接来到发布平台,以查找,发现和探索API,也可以测试、调用监控这些API。API市场的这部分是如何交互的情况如图1所示。 图1:API市场的关键组成 API管理系统为任何API市场提供一个完整的规范标准并使其能够有效运行。它通常由五个核心组件组成: API网关用作API运行时和策略执行点,强制执行限制,速率限制和安全策略。API安全性可以由网关或通过集成的身份和访问管理(IAM)基础解决方案提供。API开发平台充当目录,为应用程序开发人员提供编辑,监控和测试API的集中位置。PI开发平台提供了从后端服务设计API的功能。API分析提供API使用的快照和API货币化的Feed数据。成功实施市场需要采用更先进的方法来实现API管理系统的某些方面,尤其是API开发平台和分析。下面我们将研究构建强大API市场的五个基本要素,以促进使用API构建一个吸引更多人参与业务,增加收入流和提高忠诚度的应用程序。 API独立发布平台第一个部分是使用有效的API独立发布平台。在API市场中,API开发平台必须提供直观的体验,以支持企业开发人员方便编辑 – 无论是专业软件开发人员,业务高级用户还是长尾开发人员。API提供商可以选择在平台上受保护的注册页面后面托管所有资源和文档,或者通过向公众开放来提高透明度。使用者可以直接来到发布平台,以查找,发现和探索API,也可以测试和调用特定的API。 一个很好的例子就是我们这个大型电信服务提供商的客户,它构建了一个API驱动的应用程序/服务创建生态系统,它可以快速,轻松地创建运行在其上的数字,OTT(over-the-top)服务。依靠公司的移动通信平台,为开发人员和非开发人员提供的独立平台,为用户提供了直观的体验,可以在几分钟内查看条款和条件,注册并开始使用电信服务。 专业和平台开发人员为该平台创建的服务将在电信公司的应用商店中发布。量身定制的平台开发策略使企业能够提供来自各种开发商的应用程序,从初创企业到企业,政府机构,小型零售企业,学校,教堂和慈善机构内的非开发人员。仅在前18个月,就有超过2,500名应用创建者根据电信业务的API发布了3,300多种应用和服务。 在典型的API管理环境中,组织的API所有者发布一组API,然后由应用程序开发人员使用。然而,为了使这个概念真正可持续,应用程序开发人员需要对发布的API的形式和类型有发言权。这可能包括将字段添加到API的请求,以及将许多不同的API混合到新的API以适应特定设备的约束和要求。实现这一目标的最简单方法是建立跟踪功能请求的论坛或票务系统,并促进API的消费者和生产者之间的通信。更具前瞻性的方法是API开发平台本身允许消费者使用自助式沙盒平台来混搭API并创建自己的私有API。后者为消费者提供了一个完美的平台,可以创建自己的私有API,满足应用程序的独特需求,同时维护提供商发布的官方API。 促进再利用的激励措施除了创建门户之外,企业还需要在市场中引入促进API重用的激励措施,继续推动API变现货币化。值得注意的是,在组织内,激励措施通常没有货币价值,带来的是其他的价值。例如,公司可能会维护一个排行榜,以突出顶级API发布者和应用程序开发人员,让更多人愿意使用API。 企业还可以跟踪哪些API拥有最多订户,并在开发平台上的仪表板上显示它们。允许开发人员学习和应用技能的研讨会和黑客马拉松也可以作为激励措施。在寻求向外部各方提供激励时,组织往往会采用某种形式的财务激励措施。例如,前面讨论的电信服务提供商允许用户使用预定义的模板快速创建应用程序,然后使他们能够共享从他们在公司的应用商店发布的应用程序生成的收入。 每项服务的收益分享模型对于服务的第三方创建者为70%,对于电信公司为30%。这使得该公司实现了使用其API构建的应用程序所带来的收入环比增长20%。 API货币化API正迅速成为销售或提供给应用程序开发人员的产品,从其他业务部门或使用它们的第三方组织获得收入。因此,API市场需要直接或间接货币化API的机制。通过间接货币化,公司认识到更广泛地使用API可以为其核心业务带来更多客户和交易,并扩展生态系统。一个很好的例子是StubHub,它是活动门票的主要卖家。其API计划的目标是使旅游公司,酒店和其他酒店业的生态系统能够向其客户追加活动门票。只要酒店客户使用酒店网站上的StubHub API,StubHub就能赚钱。 同时,组织可能希望采用两种类型的直接货币化。通过直接内部货币化,一个部门通常会回拨另一个部门以使用特定的API。由于资金是通过公司会计在内部分配的,因此没有实际的信用卡收费或电汇。在外部直接货币化方案中,企业销售服务,客户是外部业务,其解决方案由API提供。例如,Twilio销售的API可让Uber在Uber的移动应用程序中提供短信和电话。 总体管理在管理API市场时,企业需要保持对谁可以发布内容和位置的控制,并确保根据组织标准(如URL模式,命名约定和访问控制规则)发布正确的API。为此,他们需要确保包含有助于满足战略和合规要求的总体治理模型。 可以通过在集中式API开发平台中发布API来集中管理API。但为了避免扼杀创造力,企业可能希望考虑采用自下而上的治理策略而不是自上而下的方法。例如,企业可以选择分散的API发布模型,使每个业务部门在设计和发布API时具有自主权。 虽然主要目标是将结构应用于API的管理,但自下而上的方法通过使每个业务功能能够独立管理其各自的API(包括对这些已发布的API的更新或设计增强)来满足此要求。通过简化此任务,每个业务部门都可以在团队成员构建和公开API的过程中发挥创造性,同时确保对其进行有效管理。 如何管理API以及如何利用API进行开发、测试、发布、监控等一系列研发管理,一直是很多企业面临的问题,国内也有部分API管理平台,但最推荐的是EOLINEKR,因为能读取通过Github、Gitlab、码云等代码仓库来读取代码的注解并自动生成API文档,支持Java、PHP两种语言,和完善的自动化测试管理,能够完成利用API进行从研发测试到网关监控,再到发布运行等一系列流程的研发管理解决方案。有兴趣了解,官网:https://www.eolinker.com API分析如前所述,分析在支持API货币化方面发挥着重要作用。更广泛地说,API分析使企业能够深入了解性能,可用性和潜在安全问题的最新问题,以及随着时间的推移分析以支持决策。企业通常最熟悉批量分析,可以将其用于识别随时间发布的API的长期趋势。其中一些趋势包括错误的调用,延迟时间,跨地理位置的一般使用,随时间的注册,限制请求,异常响应警报和API健康可用性警报。 值得注意的是,通过机器学习进行的预测分析可以应用于实时和历史(批量)数据的组合,以识别诸如潜在欺诈,用户速率限制,即将发生的容量限制或其他因素等问题,以便及时做出应对。 最后,仪表板使业务和IT用户能够以有意义的方式可视化流式和批量分析的趋势,以深入了解可用数据。通过仪表板,企业可以跟踪一组常见趋势,然后根据需要指定不同的警报。例如,企业可能希望跟踪每个应用程序的API的一般用法,每个应用程序进行最多API调用的顶级用户,以及每个应用程序API使用的资源路径。 组织可能还希望使用仪表板来监控每个应用程序的错误API调用的数量。例如,在错误调用中,消息通过故障序列进行调解,并且默认情况下,API管理系统会在后端服务不可用时将API调用视为错误。其他示例仪表板包括API延迟时间,跨地理位置的API使用,随时间推移的开发人员注册以及异常响应时间警报。 与任何企业一样,成功取决于所有利益相关者的贡献和参与,通过整合这里讨论的技术和策略,企业将能够很好地利用其当前的API管理计划来创建API市场,从而推动扩张,创造新的商机并创造新的收入来源。 原标题:Key Steps to Building and Managing an Effective API Marketplace 作者:Mifan Careem,WSO2解决方案架构的高级主管 翻译和修改:隔壁王书 原文地址:https://www.infoq.com/article... 配图来源:www.softwaretestingmaterial.com 等

June 24, 2019 · 1 min · jiezi

如何真正实现由文档驱动的API设计

前言本文主要介绍了一种新的开发思路:通过反转开发顺序,直接从API文档中阅读代码。作者认为通过这种开发方式,你可以更清楚地知道文档表达出什么以及它应该如何实现。 如果单从API文档出发,由于信息量不足,通常很难了解它具体想实现的功能,正因为有这种假设的存在,使得经常在开发之后才会想起对文档进行完善。但这种习惯对于任何开发人员而言,都不是一个好事情,在一个项目中他们会被分配完成不同的任务,不管是什么任务,必须要准确理解每个功能后,才能找到合适的方法完成工作,而一份完善的文档的作用就是能让你更好的理解具体的任务。 我们面对项目验收不断临近的截止日期,更不得不将精力全都放在开发上,导致几乎没有时间处理和完善项目文档,一般只会写个大概。因此,当你发现了文档上十分简略的信息时,那只能寄希望于回忆起当时的开发细节,不然验收时根本无从说起。 如果在验收的标准中,对文档的完整度和正确性提出要求,并且用户能对此进行评级,那文档的完善程度将会大大提升。 在编写大量代码之前,如果已经在文档中记录了所需的详细信息,那么这个文档将成为开发团队的宝贵资源。因为这个文档可以在开发团队和测试人员之间共享,所有人都可以同时使用这样的API。反过来说,通过团队的交互性凸显了文档在API开发中的重要位置。 当你想找到某一个文档时,通过交互协作的方式,你能够直接从项目中调用这个文档,这将有助于开发人员在完成任务时更方便地调用API,有效减少开发人员调试接口的时间。 我们知道了API文档的重要性,下面我们讲一下文档设计应该如何设计。 3个API文档设计中重要功能这些是我认为在文档中应该存在的三个功能: 1.时刻保持同步性,这意味着如果开发过程中增加了什么内容,那么从文档中也应该马上得知,即便是进度滞后,也应该保证文档内容在即将发布时与开发进度是一致的。 2.文档内容应该提供项目整个功能的完整内容,同时实现的方法也应该记录在文档中,供开发人员回看,方便查漏补缺。 3.文档应该作为指导和规范,帮助不同分工的开发人员完成目标统一的业务,也可用于测试API,并有助于增强开发团队沟通。如果有条件的话,还可以对完善文档的人提供奖励。 基本的API文档部分如何验证API使用者的身份呢?首先你需要一个身份信息验证方案。 1.如果你使用的是OAuth,请不要忘记在文档中解释如何设置OAuth并获取API密钥。 2.你需要记录开发中遇到的错误以及它们导致的问题,你应该在文档中解释这个错误是否违反了错误标准,即失败示例。 3.你需要记录包含端点和有关如何使用它们的信息,包括请求信息和返回信息。这是API文档的最主要部分。 记录好这三个部分,你将有一个良好的开端,因为你已经有了使用API所需的大部分内容。同时对于测试人员来说,根据你的文档进行API测试会方便很多。 但这往往还是不够的,当你遇到更复杂的情况,你还得提供额外的API的非功能性方面的文档来补充说明。 API文档还应包含哪些内容1.解释API文档中每个参数作用。 2.各种语言和工具(cURL,Postman等)的API调用示例。这些示例可能会被多次使用,可以说是API文档中最重要的部分。 3.详细说明调用API时的工作流程。 4.API提供程序采用的设计原则概述,例如REST(特别是超媒体),HTTP代码等。 5.有关身份验证的信息,包括可能实现的其他方案,如OAuth或OpenID Connect。 6.有关错误处理的一般信息以及有关HTTP返回码的信息。 7.一种交互式API资源管理器,允许开发人员轻松地将所有这些信息变为现实。 开始撰写你的API文档首先要将每个功能的需求转换为文档,同时你的文档应该是可分享的。只有这样,查看的人可以通过文档获得有关如何正确开发项目的信息,尤其是需要理解文档以解释项目的内部开发人员。 在编写API项目的文档之后,如果有条件的话,最好将文档的书面注释和其他内容转换为丰富多彩的网站和其他可自定义的模板,将有助于为项目生成完整的站点。 3 个API文档模板标准在所有API文档格式中,其中有三种值得一提,因为它们允许你以手动或者自动的方式设计API: 1.Swagger和Open API。你可以轻松生成自己的API服务器代码,客户端代码和文档本身。Open API Initiative(OAI)专注于基于Swagger规范创建,发展和推广供应商中立的API描述格式。 2.RAML。RESTful API建模语言系统提供了一种能指定API使用模式的简便方法。 3.API Blueprint。这是一种基于Markdown格式的标准,可让你轻松地从文档中生成代码。 除了作者提到的三种API标准外,EOLINKER支持自动读取代码注解生成API文档,极大地提高了开发者文档撰写的效率,有兴趣看看 EOLINKER API Studio https://www.eolinker.com 总结作为开发者,如果你想保证他人能够很好地理解你的API,那么在开发中就必须清楚文档的重要性。虽然有些人也承认上述的观点,认为使用API文档启动项目是一个好主意,但实际上大多数人都还在努力编写与文档无关的内容。 如果一开始就规划好你的文档,一旦确定后,那么会有更多的时间来处理主项目的内容。从长远来看,拥有优秀的文档可以为你节省大量时间,并可以帮助你更轻松地构建项目。 原文作者:Guy Levin 翻译和修改:EOLINKER 原文地址:https://dzone.com/articles/do...

June 10, 2019 · 1 min · jiezi

探索怎样让-JS-API-具有更好的实用性

程序员的精神,不应不止于实现,更要注重优化。不应止于表面,更要研究内部机制,方能青出于蓝而胜于蓝。1.前言在上家公司开发后台管理系统的时候,频繁要处理各种数据显示的问题,一开始是实现就好。后来写多了,自己看得也难受了。就想着怎么优化代码和复用了。下面就通过一个简单的例子,怎么让 API 更加的实用,更好的复用。 1.代码的实用性,只能尽量,尽量再尽量。不会出现完美的API,或者是一次编写,永不修改的 API 。2.关于实用性,API 命名和扩展性也很重要。但之前写过文章,在这里就不重复了。[[前端开发]--分享个人习惯的命名方式](https://juejin.im/post/5b6ad6...,重构 - 设计API的扩展机制 2.举个例子比如有一个需求,有这样的数据 { cashAmount: 236700,//回款金额(分) cashDate: "2018-05-26 10:25:28",//回款时间 cashId: "SM2018022800020692",//回款ID cashStatus: 0,//回款状态 createTime: "2018-05-23 10:26:25",//创建时间 custoName: "广州测试有限公司",//回款公司名称 id: "SM2018022800020692",//回款ID merchandisers: "守候",//回款公司联系人 ordId: "SO2018022800020692",//订单ID payChannel: null,//支付方式 remark: "",//备注 userMobile: "18819222363",//回款公司联系人电话}需要对数据进行以下处理,再渲染到页面 1.cashAmount 转换成元,并保留两位小数 2.cashStatus 进行解析(0-未回款 1-已回款) 3.payChannel 进行解析 ('zfb'-支付宝,'wx'-微信支付,'cash'-现金支付,'bankTransfer'-银行转账) 4.所有值为 '' , null , undefined 的字段,全部设置为:'--' 面对这样的需要,很简单,顺手就来 let obj = { cashAmount: 236700,//回款金额(分) cashDate: "2018-05-26 10:25:28",//回款时间 cashId: "SM2018022800020692",//回款ID cashStatus: 0,//回款状态 createTime: "2018-05-23 10:26:25",//创建时间 custoName: "广州测试有限公司",//回款公司名称 id: "SM2018022800020692",//回款ID merchandisers: "守候",//回款公司联系人 ordId: "SO2018022800020692",//订单ID payChannel: null,//支付方式 remark: "",//备注 userMobile: "13226452474",//回款公司联系人电话}function setValue(obj) { let _obj=JSON.parse(JSON.stringify(obj)); //设置金额 _obj.cashAmount = (_obj.cashAmount / 100).toFixed(2); //解析回款状态 _obj.cashStatus = _obj.cashStatus === 0 ? '未回款' : '已回款'; //解析支付方式 let payChannelLabel = { 'zfb': '支付宝', 'wx': '微信支付', 'cash': '现金支付', 'bankTransfer': '银行转账' } _obj.payChannel=payChannelLabel[_obj.payChannel]; //设置默认值 for (let key in _obj){ if(_obj[key]===''||_obj[key]===null||_obj[key]===undefined){ _obj[key]='--' } } return _obj;}obj=setValue(obj);console.log(obj)结果也正确,如下图 ...

May 6, 2019 · 3 min · jiezi

认识Restful API

Restful APIREST,即Representational State Transfer的缩写。直接翻译的意思是"表现层状态转化"。它是一种互联网应用程序的API设计理念:URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作。实现基础近年来移动互联网的发展,前端设备层出不穷(手机、平板、桌面电脑、其他专用设备……),因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信,于是RESTful诞生了,它可以通过一套统一的接口为 Web,iOS和Android提供服务。常用的URL请求方式HEAD(SELECT)只获取某个资源的头部信息GET(SELECT)获取资源POST(CREATE)创建资源PATCH(UPDATE)更新资源的部分属性(很少用,一般用POST代替)PUT(UPDATE)更新资源,客户端需要提供新建资源的所有属性DELETE(DELETE)删除资源状态码状态码字段名称为:code200 OK [GET] 服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)201 CREATED [POST/PUT/PATCH] 用户新建或修改数据成功202 ACCEPTED [] 表示一个请求已经进入后台排队(异步任务)204 NO CONTENT [DELETE] 用户删除数据成功400 INVALID REQUEST [POST/PUT/PATCH] 用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的401 UNAUTHORIZED [] 表示用户没有权限(令牌、用户名、密码错误)403 FORBIDDEN [] 表示用户得到授权(与401错误相对),但是访问是被禁止的404 NOT FOUND [] 用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的406 NOT ACCEPTABLE [GET] 用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)410 GONE [GET] 用户请求的资源被永久删除,且不会再得到的422 UNPROCESABLE ENTITY [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误500 INTERNAL SERVER ERROR [*] 服务器发生错误,用户将无法判断发出的请求是否成功注意为了简便,在web设计中,有时候会统一"code:0"代表请求成功,“code:1"代表请求失败,状态码为0,对应返回data字段,状态码为1对应返回message字段.

March 9, 2019 · 1 min · jiezi

来自Google资深工程师的API设计最佳实践

来自Google资深工程师Joshua Bloch的分享:API设计最佳实践为什么API设计如此重要?API是一个公司最重要的资产。为什么API的设计对程序员如此重要?API一旦发布,出于兼容性考虑,不能轻易地随心所欲进行修改,比如删除参数。从API的上帝 - 设计者的视角出发,有助于提高代码质量。一个优秀的API应该满足下列标准:易学易用,甚至是自描述的,不需文档也能让新手快速上手。不易造成误解。后续维护者易于理解,满足开闭原则 - 能够很容易进行扩展。如何设计一个好的API首先应该从收集需求出发。注意结合API实现的复杂度一起考虑。作为第一步,首先给出需求规格文档,一页即可:别指望你的API能让所有人满意。也不要指望发布后,它不会出任何错误——那是不可能的。API也应该遵循单一职责:如果你发觉很难根据你的API实现的功能给它取个合适的名字,这是一个不好的信号,很多时候说明你的API里面做了太多事情——试着把它们拆成多个API。信息封装 - 公有类尽量避免暴露公有字段出去,最大化信息隐藏API命名艺术 - API的名称也是一门语言。API和文档的关系合理使用继承和子类,不要滥用里氏替换原则采用fail fast 策略,尽可能早地抛出错误消息:API的数据都应该允许使用者通过字符串的方式访问慎用重载选用合适的API参数和返回类型API里的参数顺序也很有讲究避免冗长的参数列表,参数如果超过3个,使用者就需要通过阅读文档才能消费了。尽量返回不需要调用者进行异常处理的参数,比如空数组或集合,而不是nullAPI设计里的和异常处理相关的最佳实践API重构的最佳实践API设计和Thread-local相关的最佳实践要获取更多Jerry的原创文章,请关注公众号"汪子熙":

January 31, 2019 · 1 min · jiezi

小聊 API

参考 How NOT to design APIs 进行总结作者的朋友的项目正在使用 Beds24 这套系统,这套系统主要就是用来做预定的,连接的是BookingAirBnB上的房源信息。而这个项目的功能就是从一些订房平台上获取可供预定的房间和日期。但是这个提供的接口服务存在着很多问题,所以作者就拿他作为反面教材愉快地吐槽了一番。我们先来看一下一个典型的getAvailabilities接口,接口连接在这里。我们暂且就称为接口A。接口 A 通过参数获取可用房间和时间,所有可选参数如下所示:{ “checkIn”: “20151001”, “lastNight”: “20151002”, “checkOut”: “20151003”, “roomId”: “12345”, “propId”: “1234”, “ownerId”: “123”, “numAdult”: “2”, “numChild”: “0”, “offerId”: “1”, “voucherCode”: “”, “referer”: “”, “agent”: “”, “ignoreAvail”: false, “propIds”: [ 1235, 1236 ], “roomIds”: [ 12347, 12348, 12349 ]}我们就来细细评鉴一下这个参数中有哪些不合理的地方。1.日期我们可以看到,在请求报文中,checkIn,lastnight,checkOut,都使用了黏在一起的年月日形式(YYYYMMDD),虽然这种形式的可读性也不差,但是对于跨语言解析的便利性上就不好说了。其实作为时间,用 ISO8601 (YYYY-MM-DD),这样的通用标准形式会更加便捷。不论是从 encode 还是 decode 来说,比如 javascript 就能用 Date.parse(YYYY-MM-DD) 直接解析出所代表的 unix timestamp。2.ID与数字如果一个数字代表是 ID,即用来描述对象唯一的数字。那么最好是用 string 类型的,比如请求结构体roomIds,propIds。如果一个数字是用来描述数量或者值的,那不要使用 string,否则会有歧义并且不好计算。如上头的numAdult,numChild。虽然上面数字与 ID 的区分并不是强制要求,但是注意,不论你使用哪一种形式,保持统一。你可以看到:roomId和roomIds,明明只是一个是另一个的集合,缺使用了两种表示形式,这不免让人误解。在说完了 Request 部分,我们看下返回的 Response。我们按照{ “checkIn”: “20190501”, “checkOut”: “20190503”, “ownerId”: “25748”, “numAdult”: “2”, “numChild”: “0”}作为请求,得到了如下的 Response:{ “10328”: { “roomId”: “10328”, “propId”: “4478”, “roomsavail”: “0” }, “13219”: { “roomId”: “13219”, “propId”: “5729”, “roomsavail”: “0” }, “14900”: { “roomId”: “14900”, “propId”: “6779”, “roomsavail”: 1 }, “checkIn”: “20190501”, “lastNight”: “20190502”, “checkOut”: “20190503”, “ownerId”: 25748, “numAdult”: 2}3.数据结构我们用心体会一下这个 response 是干嘛的…返回的内容包括了两块:客户的房间资产列表我们请求的参数以及相应的检索返回如果你是前端的话,肯定心里已经开始 mmp 了。这个 response 把所有数据都捏在了顶层数据结构中。如果我们只想获取房间列表信息的话,我还必须遍历所有数据,并自己做一个筛选??这显然十分不合理,我们再来看看房间列表。“14900”: { “roomId”: “14900”, “propId”: “6779”, “roomsavail”: 1 },他把 roomId 作为了map的 key。这看上去有点重复,我们很少会在 json 传输过程中使用把关键结果数据作为key的字典类型(dictionary)。对于数据处理方来讲,只对 value中的数据进行处理是最方便的。你额外来一个关键信息,还是作为 key,要不是 value 中包含了 roomId,真的很 cd。另外,我们看到roomsavail,roomsavail在值为0,和值为1的时候的数据类型是不一样的(应保持一致),这个也需要注意。既然我们吐槽完毕,那就看看推荐的数据结构应该是怎么样的:{ “properties”: [ { “id”: 4478, “rooms”: [ { “id”: 12328, “available”: false } ] }, { “id”: 5729, “rooms”: [ { “id”: 13219, “available”: false } ] }, { “id”: 6779, “rooms”: [ { “id”: 14900, “available”: true } ] } ], “checkIn”: “2019-05-01”, “lastNight”: “2019-05-02”, “checkOut”: “2019-05-03”, “ownerId”: 25748, “numAdult”: 2}增加了 properties 数据块,很明确区分了数据内容,方便取用。4.错误处理万能的 200如果你知道我在说什么的话,你应该也经历过这样的问题~我们看看 Beds24 接口的错误返回码:他们定义了一套自己的错误码和错误返回信息。但是这些都是封装在200返回码的 Response 中的。这里我想说一下,我不太同意原作者的观点,这也是国内和国外的风格差异。遵循开发效率优先的原则,我认为错误处理的返回应该对外 API,统一返回200,并注明错误在自定义 errorCode 中。这样的好处是,API对接方可以很容易区分是连接层的问题还是业务层的问题。而内部接口竟可能使用 HttpStatusCode,前端同学可以更方便获取异常。4.调用须知原文中,作者对接口调用方给到的调用建议有些意见,并不涉及太多技术细节,只是提出了接口设计原则,设计要求和思路。我们就来简单过一下…调用须知是接口提供方给到的一些调用意见和规范,我们看下 Beds24的调用须知:Calls should be designed to send and receive only the minimum required data.Only one API call at a time is allowed, You must wait for the first call to complete before starting the next API call.Multiple calls should be spaced with a few seconds delay between each call.API calls should be used sparingly and kept to the minimum required for reasonable business usage.Excessive usage within a 5 minute period will cause your account to be blocked without warning.We reserve the right to disable any access we consider to be making excessive use of the API functions at our complete discretion and without warning.我们大概分析下,1和4的意见还是挺在理的,尽可能保证请求数据的最小化,合理化。第二条:每次只允许单个 api 的请求,只有当上一个请求结束后才能开始下一个请求。我觉得应该是文档好久没更新了…在当下并发与并行横行的年代,这样的接口限制有点过时。如果你是在搭建REST API,那记住,这个API是无状态的。这也是 REST API 在云应用中被广泛使用的原因,调用者无需在意是否一次一请求,一旦程序出现问题,或者上一个请求超时、异常,完全可以立即重新请求。要求调用者每次只能请求一次也是一个无理要求。第三条:复合请求每次要排队,每次间隔几秒钟。第五条:五分钟内过高的请求频率会导致账户冻结。第六条:接口提供方保留冻结接口使用者的账户的权利。有点霸王条约,而且条件说明不清晰,包括冻结条件,同时在接口请求限制上有点严格。5.文档展现推荐使用接口展示的工具,Swagger或者Apiary。Beds24的接口文档可谓是十分原汁原味了,没有主要的 index 引导,很容易让开发者看得云里雾里。6.安全这里原作者主要吐槽了 Beds24 接口不需要鉴权也能够调用的 BUG。既然说到了安全,我们就稍微延展一下。如今常见的 API 调用鉴权方式主要有以下几种:Basic AuthorizationOauth TokenSessionBasic Authorization鉴权的方式相对简单,就是在 Http Header 增加经过base64运算后的 username + password。相信你能够发现,这样的鉴权方式没有过期时间,传输内容安全验证的措施,所以如果你的 api 需要上述两个方面的保证的话,不建议使用这种鉴权方式。Session通过一个唯一的 key,验证在共享内存中的用户状态。单实例应用常用的解决方案。唯一的问题在于,共享内存中的隔离机制,因为是共享 session 的,所以 session 的读取安全性很重要。Oauth Token不同与 Session, Oauth Token(下面简称 token)不需要在共享内存中记录用户状态。token 本身就会包含用户的基本信息、权限范围、有效时间,当然这些都是经过加密的。调用者将 token 放在 http header 中进行请求。一般提供 Oauth 验证方式的接口,都会附加一个类似刷新 refresh token 的接口,用来解决 token 过期的问题。*关于详细的鉴权方式和实现大家可以 Google一下,或者 github 一下。提供一个优质、可用、易读的 API 也是每个接口提供方的责任。记得前段时间Ant Design的彩蛋事件,所引出的“开源即责任”,更何况是收费模式下的接口服务呢?文章末尾,作者好心劝告了大家,如果遇到类似Beds24的接口,请远离,除非这个接口提供的服务是不可替代的,因为这样的接口会让你投入更多的理解、纠错成本。当然,我们作为开发者,自己也要谨记在设计 API 的时候不要出现上述的一些问题。 ...

January 29, 2019 · 2 min · jiezi