草庐IT

HTTP API接口设计规范

懂电商API接口的Jennifer 2023-04-02 原文

1. 所有请求使用POST方法

  • 使用post，相对于get的query string，可以支持复杂类型的请求参数。例如日常项目中碰到get请求参数为数组类型的情况。

  • 便于对请求和响应统一做签名、加密、日志等处理

2. URL规则

  • URL中只能含有英文，使用英文单词或简称，不要使用汉语拼音

  • 所有字符使用小写字母

  • 多个单词之前使用连字符-分隔，如third-login, 不要使用thirdlogin,thirdLogin或third_login

  • URL的path部分使用 系统/模块/操作 的格式，如 ims/video/list

    • 系统，表示这个接口是微服务中的哪个服务，可使用简称
    • 模块，表示系统的子模块。模块名字使用名词全称，且使用单数形式
    • 操作，表示具体的接口，使用动词+名词的形式，需要考虑单复数。比如add-user,list-users,delete-users

3. HTTP头部

  • 将具体业务无关的数据放在HTTP headers
  • 后端系统可以在不涉及请求和响应体的情况下，处理一些公用逻辑

4. 请求和响应体

  • 使用utf-8编码
  • JSON格式
  • 如果需要加密，可以将正常的JSON加密后用base64编码

5. HTTP状态码

  • 业务的处理结果不体现在http状态码，由响应体的错误码字段表示
  • 只是有部分http状态码表示业务无关的响应，例如
    • 200: 业务已处理，但是处理成功还是失败由响应体表示
    • 400: 错误的请求，多用在请求参数验证。客户端开发要保证向服务器提交正确格式的请求
    • 401: 认证失败，一般没有token或者没有token过期
    • 403: 没有权限调用这个接口。客户端应该隐藏用户无权限的操作
    • 500: 服务器异常

6. 字段命名

  • JSON来自javascript语言，所以字段命名遵循javascript语言，使用 lowerCamelCase 小骆驼拼写法
  • 不要使用下划线链接的 snake_case

7. 数据类型

常用数据类型映射

  • bool：映射为 string，使用Y表示true，N表示false
  • int: 映射为number
  • long: 映射为string，因为js的number类型能处理的数值范围不够，实际项目中会导致各种奇怪的问题
  • float, double, decimal: 映射为string
  • 日期、时间:映射为string

注意：

  • 表示ID概念的字段，统一使用string
  • 数据传输时，如果某个字段为空值，直接省略这个字段不传，减少网络开销
  • 响应体业务数据包含多个数据结构时，优先使用嵌套格式,例如下面这个用户创建的消息
 "item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",

8. 响应体格式

  • code 业务处理的错误码，使用简短的能够体现错误种类的英文单词表示，使用大写字母，使用下划线分隔单词。不建议用数字表示错误码，用数字表示需要额外维护错误码表。

 

HTTPAPIcodexff0c34http$设计规范$网络协议

有关HTTP API接口设计规范的更多相关文章

  1. ruby-on-rails - Rails - 子类化模型的设计模式是什么？ - 2

    我有一个模型:classItem项目有一个属性“商店”基于存储的值，我希望Item对象对特定方法具有不同的行为。Rails中是否有针对此的通用设计模式？如果方法中没有大的if-else语句，这是如何干净利落地完成的？ 最佳答案 通常通过Single-TableInheritance. 关于ruby-on-rails-Rails-子类化模型的设计模式是什么？，我们在StackOverflow上找到一个类似的问题： https://stackoverflow.co

  2. ruby-on-rails - 使用 rails 4 设计而不更新用户 - 2

    我将应用程序升级到Rails4，一切正常。我可以登录并转到我的编辑页面。也更新了观点。使用标准View时，用户会更新。但是当我添加例如字段:name时，它​​不会在表单中更新。使用devise3.1.1和gem'protected_attributes'我需要在设备或数据库上运行某种更新命令吗？我也搜索过这个地方，找到了许多不同的解决方案，但没有一个会更新我的用户字段。我没有添加任何自定义字段。 最佳答案 如果您想允许额外的参数，您可以在ApplicationController中使用beforefilter，因为Rails4将参数

  3. postman接口测试工具-基础使用教程 - 2

    1.postman介绍Postman一款非常流行的API调试工具。其实，开发人员用的更多。因为测试人员做接口测试会有更多选择，例如Jmeter、soapUI等。不过，对于开发过程中去调试接口，Postman确实足够的简单方便，而且功能强大。2.下载安装官网地址:https://www.postman.com/下载完成后双击安装吧，安装过程极其简单，无需任何操作3.使用教程这里以百度为例,工具使用简单，填写URL地址即可发送请求，在下方查看响应结果和响应状态码常用方法都有支持请求方法:getpostputdeleteGet、Post、Put与Delete的作用get：请求方法一般是用于数据查询，

  4. LC滤波器设计学习笔记（一）滤波电路入门 - 2

    目录前言滤波电路科普主要分类实际情况单位的概念常用评价参数函数型滤波器简单分析滤波电路构成低通滤波器RC低通滤波器RL低通滤波器高通滤波器RC高通滤波器RL高通滤波器部分摘自《LC滤波器设计与制作》，侵权删。前言最近需要学习放大电路和滤波电路，但是由于只在之前做音乐频谱分析仪的时候简单了解过一点点运放，所以也是相当从零开始学习了。滤波电路科普主要分类滤波器：主要是从不同频率的成分中提取出特定频率的信号。有源滤波器：由RC元件与运算放大器组成的滤波器。可滤除某一次或多次谐波，最普通易于采用的无源滤波器结构是将电感与电容串联，可对主要次谐波（3、5、7）构成低阻抗旁路。无源滤波器：无源滤波器，又称

  5. 计算机毕业设计ssm+vue基本微信小程序的小学生兴趣延时班预约小程序 - 2

    项目介绍随着我国经济迅速发展,人们对手机的需求越来越大,各种手机软件也都在被广泛应用,但是对于手机进行数据信息管理,对于手机的各种软件也是备受用户的喜爱小学生兴趣延时班预约小程序的设计与开发被用户普遍使用,为方便用户能够可以随时进行小学生兴趣延时班预约小程序的设计与开发的数据信息管理,特开发了小程序的设计与开发的管理系统。小学生兴趣延时班预约小程序的设计与开发的开发利用现有的成熟技术参考,以源代码为模板,分析功能调整与小学生兴趣延时班预约小程序的设计与开发的实际需求相结合,讨论了小学生兴趣延时班预约小程序的设计与开发的使用。开发环境开发说明：前端使用微信微信小程序开发工具：后端使用ssm：VU

  6. ruby-on-rails - 设计注册确认 - 2

    我在我的项目中有一个用户和一个管理员角色。我使用Devise创建了身份验证。在我的管理员角色中，我没有任何确认。在我的用户模型中，我有以下内容:devise:database_authenticatable,:confirmable,:recoverable,:rememberable,:trackable,:validatable,:timeoutable,:registerable#Setupaccessible(orprotected)attributesforyourmodelattr_accessible:email,:username,:prename,:surname,:

  7. ruby - gem 规范失败 - 2

    我正在为毕业设计开发GEM，TravisCI构建不断失败。这是我在Travis上的链接:https://travis-ci.org/ricardobond/perpetuus/builds/8709218构建错误是:$bundleexecrakerakeaborted!Don'tknowhowtobuildtask'default'/home/travis/.rvm/gems/ruby-1.9.3-p448/bin/ruby_noexec_wrapper:14:in`eval'/home/travis/.rvm/gems/ruby-1.9.3-p448/bin/ruby_noexec_

  8. ruby-on-rails - 设计通过 reset_password_token 获取用户 - 2

    我正在尝试创建密码规则来设计可恢复的密码更改。我通过passwords_controller.rb做了一个父类(superclass)，但我需要在应用规则之前检查用户角色，但我所拥有的只是reset_password_token。 最佳答案 假设您的模型是用户:User.with_reset_password_token(your_token_here)Source 关于ruby-on-rails-设计通过reset_password_token获取用户，我们在StackOverflow

  9. ruby-on-rails - Rails 5，公寓和设计 : sign in with subdomains are not working - 2

    我已经使用Apartment设置了一个Rails5应用程序(1.2.0)和Devise(4.2.0)。由于某些DDNS问题，应用只能在app.myapp.com下访问(请注意子域app)。myapp.com重定向到app.myapp.com。我的用例是每个注册该应用的用户(租户)都应该通过他们的子域(例如tenant.myapp.com)访问他们的特定数据。用户不应限定在其子域内。基本上应该可以从任何子域登录。重定向到租户的正确子域由ApplicationController处理。根据Devise标准，登录页面位于app.myapp.com/users/sign_in。这就是问题开始的

  10. ruby-on-rails - 设计中的 ArgumentError::RegistrationsController#new 错误的参数数量(2 代表 0..1) - 2

    我在关注RyanbatesRailsCast的devise和omniauth(第235集-devise-and-omniauth-revised)。当我尝试使用Twitter登录时，标题中不断出现错误。defself.new_with_session(params,session)ifsession["devise.user_attributes"]new(session["devise.user_attributes"],without_protection:true)do|user|user.attributes=paramsuser.valid?end完整跟踪:C:/Ruby20

随机推荐