做海报创客贴同类网站,湖北建设执业资格注册中心网站,html网站首页设计,核酸结果查询1. 域名
应该尽量将API部署在专用域名之下。
https://api.example.com 如果确定API很简单#xff0c;不会有进一步扩展#xff0c;可以考虑放在主域名下。
https://www.example.org/api/2. 版本#xff08;Versioning#xff09;
应该将API的版本号放入URL。
http://…1. 域名
应该尽量将API部署在专用域名之下。
https://api.example.com 如果确定API很简单不会有进一步扩展可以考虑放在主域名下。
https://www.example.org/api/2. 版本Versioning
应该将API的版本号放入URL。
http://www.example.com/app/1.0/foohttp://www.example.com/app/1.1/foohttp://www.example.com/app/2.0/foo另一种做法是将版本号放在HTTP头信息中但不如放入URL方便和直观。Github就采用了这种做法。
因为不同的版本可以理解成同一种资源的不同表现形式所以应该采用同一个URL。版本号可以在HTTP请求头信息的Accept字段中进行区分参见Versioning REST Services
Accept: vnd.example-com.foojson; version1.0Accept: vnd.example-com.foojson; version1.1Accept: vnd.example-com.foojson; version2.03. 路径Endpoint
路径又称终点endpoint表示API的具体网址每个网址代表一种资源resource
(1) 资源作为网址只能有名词不能有动词而且所用的名词往往与数据库的表名对应。
举例来说以下是不好的例子:
/getProducts
/listOrders
/retreiveClientByOrder?orderId1对于一个简洁结构你应该始终用名词。 此外利用的HTTP方法可以分离网址中的资源名称的操作。
GET /products 将返回所有产品清单
POST /products 将产品新建到集合
GET /products/4 将获取产品 4
PATCH或PUT /products/4 将更新产品 4(2) API中的名词应该使用复数。无论子资源或者所有资源。
举例来说获取产品的API可以这样定义
获取单个产品http://127.0.0.1:8080/AppName/rest/products/1
获取所有产品: http://127.0.0.1:8080/AppName/rest/products3. HTTP动词
对于资源的具体操作类型由HTTP动词表示。
常用的HTTP动词有下面四个括号里是对应的SQL命令。
GETSELECT从服务器取出资源一项或多项。POSTCREATE在服务器新建一个资源。PUTUPDATE在服务器更新资源客户端提供改变后的完整资源。DELETEDELETE从服务器删除资源。
CURD Create、Update、Read、Delete 增删查改这四个数据库的常用操作还有三个不常用的HTTP动词。
PATCHUPDATE在服务器更新(更新)资源客户端提供改变的属性。HEAD获取资源的元数据。OPTIONS获取信息关于资源的哪些属性是客户端可以改变的。
下面是一些例子。
GET /zoos列出所有动物园
POST /zoos新建一个动物园上传文件
GET /zoos/ID获取某个指定动物园的信息
PUT /zoos/ID更新某个指定动物园的信息提供该动物园的全部信息
PATCH /zoos/ID更新某个指定动物园的信息提供该动物园的部分信息
DELETE /zoos/ID删除某个动物园
GET /zoos/ID/animals列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID删除某个指定动物园的指定动物4. 过滤信息Filtering
如果记录数量很多服务器不可能都将它们返回给用户。API应该提供参数过滤返回结果。
下面是一些常见的参数。query_string 查询字符串,地址栏后面问号后面的数据,格式: namexxsssxxx
完整的URL地址格式
协议://域名(IP):端口号/students/?查询字符串#锚点查询字符串: query_srting
格式与请求体类型usernamexiaomingclass301?limit10指定返回记录的数量
?offset10指定返回记录的开始位置。
?page2per_page100指定第几页以及每页的记录数。
?sortbynameorderasc指定返回结果按照哪个属性排序以及排序顺序。
?animal_type_id1指定筛选条件参数的设计允许存在冗余即允许API路径和URL参数偶尔有重复。比如
GET /zoos/ID/animals 与 GET /animals?zoo_idID 的含义是相同的。
6. 状态码Status Codes
1xx 表示当前本次请求还是持续没结束
2xx 表示当前本次请求成功/完成了
3xx 表示当前本次请求成功但是服务器进行代理操作/重定向
4xx 表示当前本次请求失败主要是客户端发生了错误
5xx 表示当前本次请求失败主要是服务器发生了错误服务器向用户返回的状态码和提示信息常见的有以下一些方括号中是该状态码对应的HTTP动词。 101 Switching Protocols - [*] 协议进行中一般在http升级到websocket协议的时候就看到200 OK - [GET]服务器成功返回用户请求的数据201 CREATED - [POST/PUT/PATCH]用户新建或修改数据成功。202 Accepted - [*]表示一个请求已经进入后台排队异步任务204 NO CONTENT - [DELETE]用户删除数据成功。301 Moved Permanently - [*]: 永久重定向302 Move Temporarily - [*]: 临时重定向304 Not Modified - [*]: 命中缓存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 - [*]服务器发生错误用户将无法判断发出的请求是否成功。507 Insufficient Storage [POST/PUT/PATCH] 数据存储出错往往数据库操作错误出错服务器就返回这个 状态码的完全列表参见这里或这里。
7. 错误处理Error handling
如果状态码是4xx或者5xx服务器就应该向用户返回出错信息。一般来说返回的信息中将error作为键名出错信息作为键值即可。一般格式都是json格式。
{error: Invalid API key
}8. 返回结果
restful针对不同操作服务器向用户返回的结果应该符合以下规范。
GET /collections返回资源对象的列表数组GET /collections/ID返回单个资源字典(json)POST /collections返回新生成的资源字典(json)PUT /collections/ID返回修改后的资源字典(json)DELETE /collections/ID返回一个空文档(空字符串空字典)
9. 超媒体Hypermedia API
RESTful API最好做到Hypermedia即返回结果中提供链接连向其他API方法使得用户不查文档也知道下一步应该做什么。
比如Github的API就是这种设计访问api.github.com会得到一个所有可用API的网址列表。
{
current_user_url: https://api.github.com/user,
authorizations_url: https://api.github.com/authorizations,
// ...
}从上面可以看到如果想获取当前用户的信息应该去访问api.github.com/user然后就得到了下面结果。
{message: Requires authentication,documentation_url: https://developer.github.com/v3
}上面代码表示服务器给出了提示信息以及文档的网址。
10. 其他
服务器返回的数据格式应该尽量使用JSON避免使用XML。
XMLeXtend Markup Language可扩展标记语言是W3C为了替换HTML研发出来的但是现在很明显失败了。
语法
1. xml常用场景配置文件 微信开发 小程序 安卓2. xml就是网页文档文件以 .xml结尾3. xml文档必须以文档声明开头所有的xml文档内容都必须写在自定义的根标签内xml文档有且只有1个根标签。
xml version1.0 charsetutf-8
根标签..... xml文档内容
/根标签4. xml里面也是由标签组成页面的。标签分单标签和双标签。其中单标签写法 标签名/双标签写法 标签名/标签名5. xml标签名除了文档声明其他标签名和属性全部是开发人员自己自定义的。6. 标签有0个或多个属性属性必须有属性值。而且属性值必须使用引号圈起来。
标签名 属性名属性值 .../
标签名 属性名属性值 ...标签内容/标签名xml文档举例
?xml version1.0 encodingutf-8 ?
student-list
!-- studentname小红/nameage17/agesex女/sexclass301/class/studentstudentname小红/nameage17/agesex女/sexclass301/class/student --student age17 sex男 class301小明/studentstudent age17 sex男 class301小明/studentstudent age17 sex男 class301小明/studentstudent age17 sex男 class301小明/studentstudent age17 sex男 class301小明/student
/student-listjson是目前市面上最流行的数据传输格式。JavaScript Object Notation js对象表示法
语法
# 1. json文件以 .json结尾一个json文件中只能保存一个json对象或者一个json数组
# 2. json中的属性类型数组 [] # python-列表对象 {} # python-字典数值 整型浮点型布尔值 字符串 双引号圈起来的文本内容null 空# 3. 数组和对象的成员之间必须以英文逗号隔开并且最后一个子成员后面不能出现逗号
# 4. json对象只能有属性不能出现方法而且属性名必须以字符串格式来编写举例1
{name: 张三,sex: true,age: 38,money: 88.5,child:{name: 张思,sex: false,age: 4},lve:[code,TV,swimming]
}举例2
[{name:小明,sex:true,},{name:小灰,sex:true,}
]使用xml和json表述一本书的内容信息书的字段
name varchar
price float
author varchar
pub_data date
word_total int
xml
?xml version1.0 encodingutf-8 ?
bookname金瓶梅/nameprice9999/priceauthor内容~~~适合多看/authorpub_data2020-9-8/pub_dataword_total999/word_total
/bookjson
{name:三国演义,price:1,author:诸葛亮草船借箭。。。,pub_data:2000-1-1,word_total:50
}http://www.xx.com:80/students?usernamexiaomingpwd123协议名://域名:端口/路径?查询字符串
