web接口与restful规范

web接口

接口定义:

通过网络，规定了前后台信息交互规则的url链接，在web程序中也就是联系前台页面与后台数据库的媒介.

接口特点

• url：长得像返回数据的url链接, 例如下面的搜索音乐

  • [https://api.apiopen.top/searchMusic?name=童话镇

• 请求方式：get、post、put、patch、delete

  • 采用get方式请求上方接口

• 请求参数：json或xml格式的key-value类型数据

  • name: 童话镇

• 响应结果：json或xml格式的数据

  • 上方请求参数的output参数值决定了响应数据的格式

  •   {
        code: 200,
        message: "成功!",
        result: [
          {
            author: "暗杠",
            link: "http://music.163.com/#/song?id=413829859",
            pic: "http://p2.music.126.net/xmYUW7yYS02Tc0McsGdKWA==/18345351510075909.jpg?param=300x300",
            type: "netease",
            title: "童话镇",
            lrc: "",
            songid: 413829859,
            url: "http://music.163.com/song/media/outer/ural?id=413829859.mp3"
          },
          {
            author: "李梓萌",
            link: "http://music.163.com/#/song?id=1302084285",
            pic: "http://p2.music.126.net/sGH_Ch3HCW_mE50va15Cgw==/109951163464298454.jpg?param=300x300",
            type: "netease",
            title: "童话镇 ",
            lrc: "",
            songid: 1302084285,
            url: "http://music.163.com/song/media/outer/url?id=1302084285.mp3"
          }
        ]
      }
    

restful接口规范

REST定义:

全称是 Resource Representational State Transfer：通俗来讲就是：资源在网络中以某种表现形式进行状态转移, 分解开来说明：

• Resource：资源，即数据, 比如 newsfeed，friends等；
• Representational：某种表现形式，比如用JSON，XML，JPEG等；
• State Transfer：状态变化。通过HTTP动词实现。

Restful设计方法

Restful由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了Http最初的应用协议设计理念. restful的设计一般分为2部分来看, url请求部分和response响应部分.

url

1. 用api关键字标识接口url
   api.baidu.com | www.baidu.com/api

2. 接口数据安全性决定优先选择https协议

3. 如果一个接口有多版本存在，需要在url中标识体现
   api.baidu.com/v1/... | api.baidu.com/v2/...

4. 接口操作的数据源称之为 资源，在url中一般采用资源复数形式，一个接口可以概括对该资源的多种操作方式
   api.baidu.com/books | api.baidu.com/books/(pk)

5. 请求方式有多种，用一个url处理如何保证不混乱 - 通过请求方式标识操作资源的方式

   """
   /books		get		    获取所有
   /books		post	    增加一个(多个)
   /books/(pk)	 delete		删除一个
   /books/(pk)	 put		整体更新一个
   /books/(pk)	 patch		局部更新一个
   """
   

6. 资源往往涉及数据的各种操作方式 - 筛选、排序、限制
   api.baidu.com/books/?search=西&ordering=-price&limit=3

response

1. http请求的响应会有响应状态码，接口用来返回操作的资源数据，可以拥有 操作数据结果的 状态码
   status 0(操作资源成功) 1(操作资源失败) 2(操作资源成功，但没匹配结果)
   注：资源状态码不像http状态码，一般都是后台与前台或是客户约定的
2. 资源的状态码文字提示
   status ok '账号有误' '密码有误' '用户锁定'
3. 资源本身
   results
   注：删除资源成功不做任何数据返回(返回空字符串)
4. 不能直接放回的资源(子资源、图片、视频等资源)，返回该资源的url链接