zoukankan      html  css  js  c++  java
  • restful 风格 web api规范

    协议:http/https

    域名 : http://api.example.com/xxx/xxx

    api: 标明api接口服务

    xxx: 服务

    xxx: 资源

    版本控制:

    一、使用MediaType,即在请求头header中做版本控制,数据格式等控制

    想要获取的资源格式

    GET /user/123456 HTTP/1.1 

    Accept: application/vnd.123456.user-v3+json

    获取v3版userid为123456 的用户信息,返回资源格式为json

    响应的文本格式

    HTTP/1.1 200 OK 

    Content-Type: application/vnd.123456.user-v3+json 

    {"user":  {userId":"123456","name":"张三"} } 

    服务端响应v3版userId为123456 的用户信息,返回资源格式为json

    严格遵守restful风格,可读性差

    二、URI中添加版本信息

     http://api.example.com/v1/xxx/xxx

     缺点:版本的不同会导致同一个资源对应多个uri,后期维护非常麻烦(亲身经历,令人头疼)

    三、通过传输固定参数字段 version,比较折中的方法,维护也比较方便

    动词(动作):

    GET 获取资源

    POST 创建资源

    PUT 更新资源(客户端提供改变后的完整资源)

    PATCH 更新资源(客户端提供改变的属性)

    DELETE 删除资源

    HEAD 获取资源元数据

    OPRATIONS 获取资源属性,哪些是可修改的,属性描述等等

    例:GET /user/{userId}    获取用户信息

        POST /user                创建用户

      PUT /user/{userId}    更新项目信息

    DELETE /user/{userId}  删除项目信息

    安全和幂等

    安全性:不会改变资源状态,可以理解为只读的;

    幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。

     

    安全性

    幂等性

    GET

    POST

    ×

    ×

    PUT

    ×

    PATCH

    ×

    DELETE

    ×

    HEAD

    OPRATIONS

     

     

     

     

     

     

     

     

     

     

     

    URI规则:

    1、uri 标志唯一资源,语义明确

    例:用户服务

    /user/users/{userId} 

    GET /user/users/{userId} 表示查询

    PUT /user/users/{userId} 表示更新

    单个项目是网络上的资源,一个uri唯一标识,不应该根据操作的不同,版本的不同而改变

    2、单/复数查询

    复数以对应单数名词的复数形式表示

    例:

    获取用户信息

    GET /user/users/{userId}

    获取所有用户

    GET /user/users

    获取某个用户的所有订单信息

    GET /user/users/{userId}/orders

    获取某个用户的所有某个订单信息

    GET /user/users/{userId}/orders/{orderId} 

    2、复杂查询

    restful 允许url 冗余,允许以 ?name=value的形式过滤资源信息(根据业务的具体情况需要定义一些约定参数,例order排序方式,limit 每页记录 offset 起始记录)

     

    表示

    备注

    过滤条件

    ?status=1&type=2

    资源也可以表示为

    /user/users?userId=123456

    /user/users/123456

    排序

    ?sort=time,desc

     

    投影

    ?selectlist=userId,name,status

     

    分页

    ?limit=10&offset=1

     

     

     

     

     

     

     

     

     

     

     

    例:

    获取前10条用户数据

    GET /user/users?limit=10

    获取第一页用户数据,每页显示10条

    GET /user/users?offset=1&limit=10

    按时间倒排序获取第一页项目数据,每页显示10条

    GET /user/users/?offset=1&limit=10&sort=time,desc

    响应数据

    响应数据尽可能包含全面信息

    {

        //response 状态信息

        "statusCode": 404,

        "statusLine": HTTP/1.1 200 OK,

        "requestData":{"limit":10,"offset":1},

        "responseData":{

            //业务状态

            errorCode:20001

            errorMessage:"签名无效"

            data{

                "paging":{"limit":10,"offset":1,"total":100},

                "users":[{},{},{}]

            }

      }  

    }

    响应数据可以包含另一个资源的请求信息信息

    {

        //response 状态信息

        "statusCode": 200,

        "statusLine": HTTP/1.1 200 OK

        "requestData":{"userId":"123456"},

        "responseData":{

            //业务状态

            errorCode:1

            errorMessage:"成功"

            data{

                "user":["userId":"123456",

             "blod":"http://blod.exmple.com/userId=123456"

            ]

            }

      }  

    }

  • 相关阅读:
    poj 1743 Musical Theme 后缀数组
    poj 1743 Musical Theme 后缀数组
    cf 432D Prefixes and Suffixes kmp
    cf 432D Prefixes and Suffixes kmp
    hdu Data Structure? 线段树
    关于position和anchorPoint之间的关系
    ios POST 信息
    CALayers的代码示例
    CALayers详解
    ios中得sqlite使用基础
  • 原文地址:https://www.cnblogs.com/darkwind/p/6127110.html
Copyright © 2011-2022 走看看