精华内容
下载资源
问答
  • RESTful API接口设计标准及规范;

    万次阅读 多人点赞 2019-01-12 11:42:10
    RESTful发展背景及简介 网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板...RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 REST(Representational Stat...

    RESTful发展背景及简介

    网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…)。因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现"APIFirst"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。

    REST(Representational State Transfer)表述性状态转换,REST指的是一组架构约束条件和原则。 如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。

    1. URI

    URI 表示资源,资源一般对应服务器端领域模型中的实体类。

    URI规范

    不用大写;
    用中杠-不用下杠_;
    参数列表要encode;
    URI中的名词表示资源集合,使用复数形式。

    资源集合 vs 单个资源

    URI表示资源的两种方式:资源集合、单个资源。

    资源集合:

    /zoos //所有动物园
    /zoos/1/animals //id为1的动物园中的所有动物
    

    单个资源:

    /zoos/1 //id为1的动物园
    /zoos/1;2;3 //id为1,2,3的动物园
    

    避免层级过深的URI

    /在url中表达层级,用于按实体关联关系进行对象导航,一般根据id导航。

    过深的导航容易导致url膨胀,不易维护,如 GET /zoos/1/areas/3/animals/4,尽量使用查询参数代替路径中的实体导航,如GET /animals?zoo=1&area=3;

    对Composite资源的访问

    服务器端的组合实体必须在uri中通过父实体的id导航访问。

    组合实体不是first-class的实体,它的生命周期完全依赖父实体,无法独立存在,在实现上通常是对数据库表中某些列的抽象,不直接对应表,也无id。一个常见的例子是 User — Address,Address是对User表中zipCode/country/city三个字段的简单抽象,无法独立于User存在。必须通过User索引到Address:GET /user/1/addresses

    2. Request

    HTTP方法
    通过标准HTTP方法对资源CRUD:

    GET:查询

    GET /zoos
    GET /zoos/1
    GET /zoos/1/employees
    

    POST:创建单个资源。POST一般向“资源集合”型uri发起

    POST /animals  //新增动物
    POST /zoos/1/employees //为id为1的动物园雇佣员工
    

    PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH 负责部分更新,客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起

    PUT /animals/1
    PUT /zoos/1
    

    DELETE:删除

    DELETE /zoos/1/employees/2
    DELETE /zoos/1/employees/2;4;5
    DELETE /zoos/1/animals  //删除id为1的动物园内的所有动物
    

    HEAD / OPTION 用的不多,就不多解释了。

    安全性和幂等性

    1. 安全性:不会改变资源状态,可以理解为只读的;
    2. 幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。
    .安全性幂等性
    GET
    POST××
    PUT×
    DELETE×

    安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。

    复杂查询

    查询可以捎带以下参数:

    .示例备注
    过滤条件?type=1&age=16允许一定的uri冗余,如/zoos/1/zoos?id=1
    排序?sort=age,desc 
    投影?whitelist=id,name,email 
    分页?limit=10&offset=3 

    Bookmarker

    经常使用的、复杂的查询标签化,降低维护成本。

    如:

    GET /trades?status=closed&sort=created,desc
    

    快捷方式:

    GET /trades#recently-closed
    或者
    GET /trades/recently-closed
    

    Format

    只用以下常见的3种body format:

    1.Content-Type: application/json

    POST /v1/animal HTTP/1.1
    Host: api.example.org
    Accept: application/json
    Content-Type: application/json
    Content-Length: 24
     
    {   
      "name": "Gir",
      "animalType": "12"
    }
    

    2.Content-Type: application/x-www-form-urlencoded (浏览器POST表单用的格式)

    POST /login HTTP/1.1
    Host: example.com
    Content-Length: 31
    Accept: text/html
    Content-Type: application/x-www-form-urlencoded
     
    username=root&password=Zion0101
    

    Content-Type: multipart/form-data; boundary=—-RANDOM_jDMUxq4Ot5 (表单有文件上传时的格式)

    Content Negotiation

    资源可以有多种表示方式,如json、xml、pdf、excel等等,客户端可以指定自己期望的格式,通常有两种方式:

    1.http header Accept:

    Accept:application/xml;q=0.6,application/atom+xml;q=1.0
    

    q为各项格式的偏好程度

    2.url中加文件后缀:/zoo/1.json

    6. Response

    1. 不要包装: 
      response 的 body 直接就是数据,不要做多余的包装。错误示例:

      1. {
      2. "success":true,
      3. "data":{"id":1,"name":"xiaotuan"},
      4. }
    2. 各HTTP方法成功处理后的数据格式:

      ·response 格式
      GET单个对象、集合
      POST新增成功的对象
      PUT/PATCH更新成功的对象
      DELETE
    3. json格式的约定:

      1. 时间用长整形(毫秒数),客户端自己按需解析(moment.js
      2. 不传null字段

    分页response

    {
        "paging":{"limit":10,"offset":0,"total":729},
        "data":[{},{},{}...]
    }
    

    7. 错误处理

    1. 不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;
    2. 正确设置http状态码,不要自定义;
    3. Response body 提供 1) 错误的代码(日志/问题追查);2) 错误的描述文本(展示给用户)。

    对第三点的实现稍微多说一点:

    Java 服务器端一般用异常表示 RESTful API 的错误。API 可能抛出两类异常:业务异常和非业务异常。业务异常由自己的业务代码抛出,表示一个用例的前置条件不满足、业务规则冲突等,比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题,通常由类库、框架抛出,或由于自己的代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误等等。

    业务类异常必须提供2种信息:

    1. 如果抛出该类异常,HTTP 响应状态码应该设成什么;
    2. 异常的文本描述;

    在Controller层使用统一的异常拦截器:

    1. 设置 HTTP 响应状态码:对业务类异常,用它指定的 HTTP code;对非业务类异常,统一500;
    2. Response Body 的错误码:异常类名
    3. Response Body 的错误描述:对业务类异常,用它指定的错误文本;对非业务类异常,线上可以统一文案如“服务器端错误,请稍后再试”,开发或测试环境中用异常的 stacktrace,服务器端提供该行为的开关。

    常用的http状态码及使用场景:

    状态码使用场景
    400 bad request常用在参数校验
    401 unauthorized未经验证的用户,常见于未登录。如果经过验证后依然没权限,应该 403(即 authentication 和 authorization 的区别)。
    403 forbidden无权限
    404 not found资源不存在
    500 internal server error非业务类异常
    503 service unavaliable由容器抛出,自己的代码不要抛这个异常

    8. 服务型资源

    除了资源简单的CRUD,服务器端经常还会提供其他服务,这些服务无法直接用上面提到的URI映射。如:

    按关键字搜索;
    1.计算地球上两点间的距离;
    2.批量向用户推送消息
    3.可以把这些服务看成资源,计算的结果是资源的presentation,按服务属性选择合适的HTTP方法。

    例:

    GET /search?q=filter?category=file  搜索
    GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448
    POST /batch-publish-msg
    [{"from":0,"to":1,"text":"abc"},{},{}...]
    

    9. 异步任务

    对耗时的异步任务,服务器端接受客户端传递的参数后,应返回创建成功的任务资源,其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度。

    提交任务:
    POST /batch-publish-msg
    [{"from":0,"to":1,"text":"abc"},{},{}...]
     
    返回:
    {"taskId":3,"createBy":"Anonymous","status":"running"}
     
    GET /task/3
    {"taskId":3,"createBy":"Anonymous","status":"success"}
    

    如果任务的执行状态包括较多信息,可以把“执行状态”抽象成组合资源,客户端查询该状态资源了解任务的执行情况。

    提交任务:
    POST /batch-publish-msg
    [{"from":0,"to":1,"text":"abc"},{},{}...]
     
    返回:
    {"taskId":3,"createBy":"Anonymous"}
     
    GET /task/3/status
    {"progress":"50%","total":18,"success":8,"fail":1}
    

    10. API的演进

    版本
    常见的三种方式:

    1.在uri中放版本信息:GET /v1/users/1
    2.Accept Header:Accept: application/json+v1
    3.自定义 Header:X-Api-Version: 1
    用第一种,虽然没有那么优雅,但最明显最方便。

    URI失效
    随着系统发展,总有一些API失效或者迁移,对失效的API,返回404 not found 或 410 gone;对迁移的API,返回 301 重定向。

    展开全文
  • 1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch: https://review.openstack.org/#/c/361791/ ... ...

    1.构建API接口文档标准参考:

    http://docs.openstack.org/contributor-guide/api-guides.html

    2.构建API接口文档步骤参考下面的Patch:

    https://review.openstack.org/#/c/361791/

    https://review.openstack.org/#/c/305870/

    https://review.openstack.org/#/c/305973/

    3.创建API接口文档的CI已经如何发布到OpenStack网站。

    (1)创建CI:https://review.openstack.org/#/c/305464/

    (2)发布成Html:https://review.openstack.org/#/c/305485/

    4.其他问题。

    (1) 从Project-Config项目中确认目前是否只有Nova在做这个事情?

    magnum,senlin等其他项目也在做API文档标准规范。

    (2) openstack/openstack-manuals在做什么?

    只有一个链接指向:http://developer.openstack.org/api-ref.html

    (3) openstack/api-site在做什么?

    所有项目的api-ref都已经迁移到自己的项目,所以以后的项目api-ref只需要在Karbor项目内部维护即可。

    (4) swagger是一种根据yaml来定义API的方式,Karbor设计之初采用的就是swagger,但不是OpenStack的标准规范。

    http://editor.swagger.io/#/?import=http:%2F%2Ffpaste.org%2F324841%2F81061214%2Fraw%2F

    转载于:https://www.cnblogs.com/edisonxiang/p/5832176.html

    展开全文
  • 工行开放银行api 英国政府已委托英国银行进行可行性研究,以使客户能够通过开放标准API与第三方共享交易数据。 早在12月的秋季声明中首次提到,总理现在就在3月的最新预算中概述了强制性开放银行API标准的计划。 ...

    银行开放api接口

    英国政府已委托英国银行进行可行性研究,以使客户能够通过开放标准API与第三方共享交易数据。 早在12月的秋季声明中首次提到,总理现在就在3月的最新预算中概述了强制性开放银行API标准的计划。

    创新的金融技术开发商不断加剧的竞争和银行服务的分离,继续为客户提供更多服务。 银行业的重大变革已成为必然,而乍一看,这一举动可被解释为对银行的惩罚。 它打开了一些以前控制过的信息库,但是通过开放标准API进行访问可以增强它们作为平台的地位。

    Open Bank Project的创始人Simon Redfern参加了开放标准API咨询。 我已经了解了客户和开发人员将如何从中受益,我问西蒙,银行本身是否可以通过开发开发人员喜欢使用的开放API来获利,从而通过有用的应用程序吸引新客户。

    “的确如此。这是开放银行/银行作为平台愿景,Open Bank Project通过其开放标准,开放源代码技术和社区来支持。例如,开发人员可以构建连接到英国银行以及例如,墨西哥的银行。这是一种开放标准,为银行客户带来了更多选择和实用性,因为开发人员发现易于使用REST和OAuth等互联网标准,并且如果易于部署到多家银行,则开发人员更有可能为专业市场发展。”他说。

    一个开放的API生态系统将必须具有比银行对消费者模型更多的层功能,并具有分布式经济的功能,尤其是在数据可以沿任何方向移动的mashup应用程序中尤其如此。 在这种环境下,开源为开发人员提供了无障碍构建的机会,并更有能力交付用户所需的价值。 技术驱动的金融世界的这种巨变对开源软件和开源数据的开发人员具有无数的影响。 金融技术行业已经快速成熟,甚至为那些不使用银行的人改善了金融服务。

    “对于开发人员而言,关键是一个统一的银行API。开发人员不想为了支持所有用户而集成一个完全不同的API。这就是我构建Teller的原因。开发人员集成了一个API并获得了所有银行给客户带来的好处是无数的。”位于伦敦的开发商Stevie Graham说。

    公开的银行数据将使我们能够自由地从单一视图中实时访问所有银行,并以完全透明的方式自动计算最佳交易,这对于社会福利而言将是向前迈出的重要一步,并使人们能够更好地控制自己的财务状况。 同时,金融技术孵化器,加速器和初创公司正在创建一个经验更丰富的开发人员人才库,准备对这些新可用资产采取行动。

    Xignite首席执行官Stephane Dubois表示:“技术在推动金融服务行业发展中的作用比以往任何时候都更为重要。与传统的传统系统相比,当今的银行使用API​​有助于提高速度和成本效益,因此变得越来越普遍为金融机构提供适应技术变革所需的工具和资源,具有巨大的价值,这使得新兴的API开发人员的角色对于当今的金融机构的长期成功至关重要。”

    通过一个永续发展的开发商生态系统,银行将继续通过第三方集成从客户那里收集高价值数据。

    趋势所有者克里斯蒂安·罗德斯(Christian Rhodes)对进入银行业的独立开发人员持务实的看法:“产品使市场进入市场的速度比银行所能匹敌的快得多。现在,企业不再试图建立和推动专有解决方案,而是在适应客户的需求。或者可能会采取适当措施进入开放环境。”

    翻译自: https://opensource.com/business/15/4/open-standard-api-banking

    银行开放api接口

    展开全文
  • RESTful API接口设计标准及规范学习
    展开全文
  • restful api标准,状态码返回,post、get,delete、update等方法调用规范化 restful api调用全局异常输出 logback日志输出,日志分割,打包 常用util封装 使用方法: clone项目到本地后,idea打开,直接启动Driver...
  • A类标准接口 淘宝API item_get 获取商品详情 根据商品ID查询商品标题价格描述等详情数据 淘宝API item_search 按关键字搜索商品 搜索关键字,显示商品总数,标题,图片,优惠价等数据 淘宝API item_fee 获取商品快递...
  • Restful API 接口设计标准以及规范 RESTful概念 理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和...
  • WINDOWS API接口

    2013-07-08 14:58:14
    本文提供标准windowsAPI函数接口
  • RESTful不是一种技术,而是一种接口规范,主要规范包括:1.请求方式、2.状态码、3、url规范、4、传参规范 请求方式method GET :从服务器取出资源(一项或多项) POST :在服务器新建一个资源 PUT :在服务器更新...
  • A类标准接口 淘宝API item_get 获取商品详情 根据商品ID查询商品标题价格描述等详情数据 淘宝API item_search 按关键字搜索商品 搜索关键字,显示商品总数,标题,图片,优惠价等数据 淘宝API item_fee 获取商品快递...
  • RESTful API接口设计标准及规范

    千次阅读 2020-05-24 17:23:46
    RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 REST(Representational State Transfer)表述性状态转换,REST指的是一组架构约束条件和原则。 如果一个架构符合REST的约束条件
  • ABI接口与API接口

    2020-08-19 13:58:13
    API和ABI很类似,两者的全程只有一字之隔,API(Application Programming Interface)和ABI(Application Binary Interface),其实 ... 举个例子,比如POSIX的pirntf()函数,在API层面,他能保证所有支持POSIX标准的系...
  • 一个基于COM标准的CTP-API接口封装,通过这个COM接口,用户可以利用任何支持COM的语言来接入CTP;该COM组件在内部进行仓位和资金的自动计算,并对用户屏蔽了上期所的平今和平昨的差别(优先平今),对用户非常友好。
  • 全球经济正在经历数字化转型,而数字化经济则基于数据的沟通和调用,在此背景下,能够让数据流通、应用集成更便捷、应用服务更安全的API(Application Programming Interface)应运而生,并获得迅速发展。 市场调研...
  • 使用C# ASP.NET WebAPI构建API接口服务,实现前后端分离开发。同时,可使用工具自动生成接口文档,构建标准的WebApi的Rest后台数据接口服务接口。

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 10,553
精华内容 4,221
关键字:

标准api接口