精华内容
下载资源
问答
  • 2022-03-02 17:20:06

    1、url命名风格介绍

    • 驼峰命名法
      例:http://xxxx/getUser
    • 蛇形命名法
      例:http://xxxx/get_user
    • 脊柱命名法
      示例
    https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user
    https://stackoverflow.com/questions/5262224/how-are-reddit-and-hacker-news-ranking-algorithms-used
                https://api.github.com/
    

    2、url大小写及多单词命名原则
    1) URL采用小写字母,数字,部分特殊符号(非制表符)组成。
    2) URL中不采用大小写混合的驼峰命名方式,尽量采用全小写单词,如果需要连接多个单词,则采用连接符“_”或"-“连接单词,推荐使用后者,即中横线”-"。

    3、url路径分级原则

    • 第1级:/api
      用于区分服务接口和静态资源请求,以便做权限拦截等处理。

    • 第2级:/模块名称
      对应controller名称,模块名称可以定义两级,即:/父模块名/子模块名,通常将第1级和第2级一起定义到controller路径中,例:/api/user

    • 第3级:/动作名称/版本号
      对应method名称,例:/add/v1

    4、crud url设计推荐
    新增:/api/{module-name}/add/v1
    请求方式:post,content-type:application/json

        查看:/api/{module-name}/get/{id}/v1
            使用场景:进入编辑页面,以及相关详情弹框
            请求方式:get,参数放在url中
    
        修改:/api/{module-name}/edit/{id}/v1
            请求方式:post,content-type:application/json
    
        删除:/api/{module-name}/del/{id}/v1
            请求方式:post,content-type:application/json
    
        列表(默认,带分页,带搜索):/api/{module-name}/list/v1
            请求方式:get,参数放在url中
            建议:不论是否有分页需求,结果全部按分页格式返回,默认可不传分页参数
    
        列表(非默认):/api/{module-name}/list-{datatype}/v1
    
    更多相关内容
  • RESTful 接口设计规范

    千次阅读 2021-08-03 10:20:19
    一、RESTful 接口设计规范 1. 协议 API与用户的通信协议,尽量使用HTTPs协议。 2. 域名 应该尽量将API部署在专用域名之下。 https://api.example.com 如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。 ...

    一、RESTful 接口设计规范

    1. 协议

    API与用户的通信协议,尽量使用HTTPs协议。

    2. 域名

    应该尽量将API部署在专用域名之下。
    https://api.example.com
    如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
    https://example.org/api/

    3. 版本

    应该将API的版本号放入URL。
    https://api.example.com/v1/
    另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。
    Github采用这种做法。

    4. 路径

    路径又称“终点"(endpoint),表示API的具体网址。
    在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的“集合"(collection),所以API中的名词也应该使用复数。

    举例来说,有一个APl提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。

    • https://api.example.com/v1/zoos
    • https://api.example.com/v1/animals
    • https://api.example.com/v1/employees

    5. HTTP 动词

    对于资源的具体操作类型,由HTTP动词表示。
    常用的HTTP动词有下面五个(括号里是对应的SQL命令)。

    • GET(读取):从服务器取出资源(一项或多项)。
    • POST(创建):在服务器新建一个资源。
    • PUT(完整更新):在服务器更新资源(客户端提供改变后的完整资源)。
    • PATCH(部分更新):在服务器更新资源(客户端提供改变的属性)。
    • DELETE(删除):从服务器删除资源。

    还有两个不常用的HTTP动词。

    • HEAD:获取资源的元数据。
    • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

    下面是一些例子。

    • GET/zoos:列出所有动物园
    • POST/zoos:新建一个动物园
    • GET/z00S/ID:获取某个指定动物园的信息
    • PUT/zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
    • PATCH/zooS/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
    • DELETE/zoos/ID:删除某个动物园
    • GET/zooS/ID/animals:列出某个指定动物园的所有动物
    • DELETE/zoos/ID/animals/ID:删除某个指定动物园的指定动物

    6. 过滤信息

    如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。

    下面是一些常见的参数。

    • ?limit=10:指定返回记录的数量
    • ?offset=10:指定返回记录的开始位置。
    • ?page=2&per_page=100:指定第几页,以及每页的记录数。
    • ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
    • ?animal_type_id=1:指定筛选条件

    参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。
    比如,GET/zo0/ID/animals 与 GET/animals?zoo_id=ID的含义是相同的。

    7. 状态码

    客户端的每一次请求,服务器都必须给出回应。回应包括HTTP状态码和数据两部分。

    HTTP状态码就是一个三位数,分成五个类别。

    • 1xx:相关信息
    • 2xx:操作成功。
    • 3xX:重定向
    • 4xx:客户端错误
    • 5xx:服务器错误

    这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。

    常见的有以下一些(方括号中是该状态码对应的HTTP动词)。

    • 200OK-[GET]:服务器成功返回用户请求的数据,该操作是幂等的(ldempotent)。
    • 201 CREATED-[POST/PUT/PATCH]:用户新建或修改数据成功。
    • 202 Accepted-[*]:表示一个请求已经进入后台排队(异步任务)
    • 204 NO CONTENT-[DELETE]:用户删除数据成功。
    • 400 INVALID REQUEST-[POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
    • 401 Unauthorized-[]:表示用户没有权限(令牌、用户名、密码错误)。
    • 403 Forbidden-[*]表示用户得到授权(与401错误相对),但是访问是被禁止的。
    • 404NOT FOUND-[*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
    • 406 Not Acceptable-[GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
    • 410Gone-[GET]:用户请求的资源被永久删除,且不会再得到的。
    • 422 Unprocesable entity-[POST/PUT/PATCH]当创建一个对象时,发生一个验证错误。
    • 500 INTERNAL SERVER ERROR-[*]:服务器发生错误,用户将无法判断发出的请求是否成功。

    8. 返回结果

    API返回的数据格式,不应该是纯文本,而应该是一个JSON对象,因为这样才能返回标准的结构化数据。所以,服务器回应的HTTP头的Content-Type 属性要设为application/json

    针对不同操作,服务器向用户返回的结果应该符合以下规范。

    • GET/collection:返回资源对象的列表(数组)
    • GET/collection/resource:返回单个资源对象
    • POST/collection:返回新生成的资源对象
    • PUT/collection/resource:返回完整的资源对象
    • PATCH/collection/resource:返回完整的资源对象
    • DELETE/collection/resource:返回一个空文档

    9. 错误处理

    有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。
    在这里插入图片描述
    上面代码中,解析数据体以后,才能得知操作失败。

    这种做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。
    在这里插入图片描述

    10. 身份认证

    基于JWT的接口权限认证:

    • 字段名:Authorization
    • 字段值:Bearer token数据

    11. 跨域处理

    可以在服务端设置CORS允许客户端跨域资源请求。

    展开全文
  • RESTful API设计规范

    2022-03-29 10:25:33
    详细介绍RESTful的设计规范

    前言

    RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计。

    它的大原则容易把握,但是细节不容易做对。本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API。


    一、 URL设计

    1.动词+宾语

    RESTful的核心思想就是,客户端发出的数据+操作指令都是“动词+宾语”的结构,比如GET /orders这个命令,GET是动词,/orders是宾语,动词通常就有5种HTTP请求方法,对应CRUD操作,根据 HTTP 规范,动词一律大写。

    # GET:读取(Read)
    # POST:新建(Create)
    # PUT:更新(Update)
    # PATCH:更新(Update),通常是部分更新
    # DELETE:删除(Delete)
    

    2.动词的覆盖

    有些客户端只能使用GETPOST这两种方法。服务器必须接受POST模拟其他三个方法(PUTPATCHDELETE)。这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

    POST /api/Person/4 HTTP/1.1  
    X-HTTP-Method-Override: PUT
    

    上面代码中,X-HTTP-Method-Override指定本次请求的方法是PUT,而不是POST

    3.宾语必须是名词

    宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/orders这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

    # /getAllOrders
    # /createNewOrder
    # /deleteAllOrders
    

    4.复数 URL

    既然 URL 是名词,那么应该使用复数,还是单数?这没有统一的规定,但是常见的操作是读取一个集合,比如GET/orders(读取所有文章),这里明显应该是复数。

    为了统一起见,建议都使用复数 URL,比如GET/orders/2要好于GET /order/2

    5.避免多级 URL

    常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。

    # GET /authors/12/categories/2
    

    这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。

    更好的做法是,除了第一级,其他级别都用查询字符串表达。

    # GET /authors/12?categories=2
    

    下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。

    # GET /orders/published
    

    查询字符串的写法明显更好

    # GET /orders?published=true
    

    二、状态码

    状态码必须精确

    客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

    HTTP 状态码就是一个三位数,分成五个类别。

    # 1xx:相关信息
    # 2xx:操作成功
    # 3xx:重定向
    # 4xx:客户端错误
    # 5xx:服务器错误
    

    这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。

    API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。

    2XX状态码

    200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

    # GET: 200 OK
    # POST: 201 Created
    # PUT: 200 OK
    # PATCH: 200 OK
    # DELETE: 204 No Content
    

    上面代码中,POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。

    此外,202 Accepted状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。下面是一个例子。

    HTTP/1.1 202 Accepted
    
    {
      "task": {
        "href": "/api/company/job-management/jobs/2130040",
        "id": "2130040"
      }
    }
    

    3xx 状态码

    API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。

    API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。它与302307的含义一样,也是"暂时重定向",区别在于302307用于GET请求,而303用于POSTPUTDELETE请求。收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。下面是一个例子。

    HTTP/1.1 303 See Other
    Location: /api/orders/12345
    

    4xx 状态码

    4xx状态码表示客户端错误,主要有下面几种。

    400 Bad Request:服务器不理解客户端的请求,未做任何处理。

    401 Unauthorized:用户未提供身份验证凭据,或者没有通过身份验证。

    403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。

    404 Not Found:所请求的资源不存在,或不可用。

    405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。

    410 Gone:所请求的资源已从这个地址转移,不再可用。

    415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON `格式,但是客户端要求返回 XML 格式。

    422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。

    429 Too Many Requests:客户端的请求次数超过限额。

    5xx 状态码

    5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

    500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。

    503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。

    三、 URL设计

    不要返回纯本文

    API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json

    客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

    GET /orders/2 HTTP/1.1 
    Accept: application/json
    

    发生错误时,不要返回 200 状态码

    有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "status": "failure",
      "data": {
        "error": "Expected at least two items in list."
      }
    }
    

    上面代码中,解析数据体以后,才能得知操作失败。

    这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
      "error": "Invalid payoad.",
      "detail": {
         "surname": "This field is required."
      }
    }
    

    提供链接

    API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。

    举例来说,GitHub 的 API 都在 api.github.com 这个域名。访问它,就可以得到其他 URL。

    {
      ...
      "feeds_url": "https://api.github.com/feeds",
      "followers_url": "https://api.github.com/user/followers",
      "following_url": "https://api.github.com/user/following{/target}",
      "gists_url": "https://api.github.com/gists{/gist_id}",
      "hub_url": "https://api.github.com/hub",
      ...
    }
    

    上面的回应中,挑一个 URL 访问,又可以得到别的 URL。对于用户来说,不需要记住 URL 设计,只要从 api.github.com 一步步查找就可以了。

    HATEOAS 的格式没有统一规定,上面例子中,GitHub 将它们与其他属性放在一起。更好的做法应该是,将相关链接与其他属性分开。

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "status": "In progress",
       "links": {[
        { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
        { "rel":"edit", "method": "put", "href":"/api/status/12345" }
      ]}
    }
    
    展开全文
  • HTTP RESTful规范说明

    2021-03-25 20:17:26
    1. API的就是程序员的UI,和其他UI一样,必须仔细考虑它的用户体验! 几个必须的原则: 当标准合理的时候遵守标准。 API应该对程序员友好,并且在浏览器地址栏容易输入。 API应该简单,直观,容易使用的同时优雅。...

    1. API的就是程序员的UI,和其他UI一样,必须仔细考虑它的用户体验!

    几个必须的原则:

    1. 当标准合理的时候遵守标准。
    2. API应该对程序员友好,并且在浏览器地址栏容易输入。
    3. API应该简单,直观,容易使用的同时优雅。
    4. API应该具有足够的灵活性来支持上层ui。
    5. API设计权衡上述几个原则。

    2. URL设计

    REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作(GET ,POST,PUT,DELETE). 显然从API用户的角度来看,”资源“应该是个名词。即使你的内部数据模型和资源已经有了很好的对应,API设计的时候你仍然不需要把它们一对一的都暴露出来。这里的关键是隐藏内部资源,暴露必需的外部资源。

    URL遵循动词+宾语的结构

    2.1 动词

    请求含义
    GET读取/Read
    POST新建/Create
    PUT更新/Update
    PATCH部分更新/Update
    DELETE删除/Delete

    2.2 宾语

    宾语必须为名词且最好为复数,同时要避免多级URL,可通过参数来展示分类. 使用复数使得URL更加规整, 这让API使用者更加容易理解,对开发者来说也更容易实现.

    一旦定义好了要暴露的资源,你可以定义资源上允许的操作,以及这些操作和你的API的对应关系:

    • GET /tickets           # 获取所有ticket列表
    • GET /tickets/12            # 查看某个具体的ticket(id为12)
    • POST /tickets               # 新建一个ticket
    • PUT /tickets/12            # 更新ticket(id为12)
    • DELETE /tickets/12     # 删除ticekt(id为12)

    可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里只需要一个endpoint:/tickets, 再没有其他什么命名规则和url规则了.

    2.3 处理资源关联

    如何处理关联?关于如何处理资源之间的管理REST原则也有相关的描述:

    • GET /tickets/12/messages               # 获取ticket(id为12)的所有messages列表
    • GET /tickets/12/messages/5           # 获取ticket(id为12)的某个具体message(id为5)
    • POST /tickets/12/messages            # 为ticket(id为12)新建一个message
    • PUT /tickets/12/messages/5           # 更新ticket(id为12)的message(id为5)
    • PATCH /tickets/12/messages/5      # 部分更新ticket(id为12)的message(id为5)
    • DELETE /tickets/12/messages/5    # 删除ticket(id为12)的message(id为5)

    其中,如果这种关联和资源独立,那么可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息。(例如这里如果message资源是独立存在的,那么上面 GET /tickets/12/messages就会返回相应message的链接;相反的如果message不独立存在,他和ticket依附存在,则上面的API调用返回直接返回message信息)

    2.4 版本化

    在API上加入版本信息可以有效的防止用户访问已经更新了的API,同时也能让不同主要版本之间平稳过渡。

    版本化API的通常方式有:

    2.4.1 URI中设置版本

    这种方式通常在URI中增加一段用于标识版本,例如/v1/v2等。例如:

    curl https://example.com/api/v2/lists/3
    

    这种方式的优势在于版本信息很容易明显的看出来,可以通过浏览器直接访问。

    2.4.2 HTTP头中设置版本

    这种方式的版本信息会放在HTTP的请求头中,通常会利用Accept字段,或者自定义一个字段。例如:

    curl https://example.com/api/lists/3 \  
    -H 'Accept: application/vnd.example.v2+json'
    

    这种方式的好处是当版本升级时,URI保持不变,并且仅用于表示资源定位。

    2.4.3 没有版本

    版本化的目的是为了标识API的变化,如果API不会变化,或者每次都会重新扩展新的API,这种情况下,就可以标识版本信息。例如:

    curl https://example.com/api/lists/3
    
    2.4.4 一种折中方案

    前面提到了三种版本化API的方式,通常情况下需要针对自己业务的特殊性来挑选其中的一种方式。但是,在实际应用场景中,情况会更加复杂,API的升级通常有两种情况:

    1. 大版本更新,例如字段类型变更、数据对象变更等。这种情况下无法满足对客户端的向下兼容,因此需要修改版本号。
    2. 小版本更新,例如增加可选参数、增加返回字段等。这种情况对于新客户端可以增加功能,对于老客户端仍然可以保持原有功能,可以不修改版本号。

    因此,折中方案是基于URI中的大版本号和HTTP头中的小版本号整合的方式。下面通过一个简单的示例来解释。

    用户管理平台

    一个常用的用户管理平台,提供以下API,通过用户ID获取用户信息:

    curl https://example.com/api/v1/user/1
    ...
    {
      "id": 1,
      "name": "test",
      "email": "test@example.com"
    }
    

    考虑以下两种变动情况:一种是用户id从数字变成了字符串,另一种是新增一个用户头像的值。

    前者修改因为数据类型的变化,会导致客户端解析出现问题。因此这样的修改已经破坏了向下兼容性,此时就需要修改API的版本号。例如:

    curl https://example.com/api/v2/user/1
    ...
    {
      "id": "1",
      "name": "test",
      "email": "test@example.com"
    }
    

    第二种情况,对于旧客户端来说,只是增加了不使用的字段,通常的JSON格式解析库都可以忽略这些不使用的字段。对于新客户端则可以读取新的字段。例如:

    curl https://example.com/api/v2/user/1
    ...
    {
      "id": "1",
      "name": "test",
      "email": "test@example.com",
      "avatar": "http://example.com/1.jpg"
    }
    

    这种情况下,基本可以做到向下兼容,因此可以算是“小版本升级”。针对小版本升级,可以将小版本号放到HTTP头中。例如:

    curl https://example.com/api/v2/user/1 \
        -H 'API-VERSION: 20170801'
    ...
    {
      "id": "1",
      "name": "test",
      "email": "test@example.com",
      "avatar": "http://example.com/1.jpg"
    }
    
    2.4.5 后端路由

    由于混合版本化的方式同时涉及到URI和HTTP头字段,前端代理(例如HAProxy、nginx)可以通过这些特定版本号字段将请求代理到对应的后端应用。

    例如,前端使用HAProxy进行多版本分发,可以针对URI和HTTP头定制acl,然后再对这些acl进行组合,设置不同的backend。

    acl is_v1 path_beg /api/v1
    acl is_v2 path_beg /api/v2
    acl is_version_1 hdr(API-VERSION) 20170801
    acl is_version_2 hdr(API-VERSION) 20170701
    use_backend old_server if is_v1 is_version_1
    use_backend new_server if is_v2 is_version_2
    backend old_server
    ...
    backend new_server
    ...
    

    这样可以将API版本化规则应用到不同的后端,以保证向下兼容性。

    2.4.6 总结

    基于版本化API规则,将“大版本”应用在URI上,将“小版本”应用在HTTP头字段上。通常来说,如果API升级之后破坏了向下兼容性,就应该升级“大版本”号;如果API升级可以向下兼容,可以升级“小版本”号。

    版本化API有很多不同的设计方式,实际应用时,还是要根据业务场景进行选择,包括API版本升级频率,API稳定性等。通过HAProxy、nginx等代理服务,可以在确保向下兼容的情况下,由业务方决定老版本API的保留时间。

    URL设计

    URL遵循动词+宾语的结构

    3.状态码

    1xx 相关信息

    API不需要1xx状态码

    2xx 操作成功

    状态码含义
    200 OK成功
    201 Created生成了新的资源
    202 Accepted已经收到请求但还未处理完成/异步操作
    204 No Content(删除时)资源已不存在

    3xx 重定向

    状态码含义
    301 Moved Permanently永久重定向/资源的URL已被更新-API用不到
    302暂时重定向/用于GET请求-API用不到
    303 See Other暂时重定向/用于POST/PUT/DELETE请求
    304 Not Modified资源未更改/缓存
    307暂时重定向/用于GET请求-API用不到

    4xx 客户端错误

    状态码含义
    400 Bad Request服务器不理解客户端的请求,未做任何处理
    401 Unauthorized用户未提供身份验证凭据,或者没有通过身份验证
    403 Forbidden用户通过了身份验证,但是不具有访问资源所需的权限
    404 Not Found所请求的资源不存在,或不可用
    405 Method Not Allowed用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内
    406 Not Acceptable服务端不支持所需表示/参数格式错误
    409 Conflict通用冲突
    410 Gone所请求的资源已从这个地址转移,不再可用
    412 Precondition Failed前置条件失败(如执行条件更新时的冲突)
    415 Unsupported Media Type客户端要求的返回格式不支持
    422 Unprocessable Entity客户端上传的附件无法处理,导致请求失败
    429 Too Many Requests客户端的请求次数超过限额

    5xx 服务端错误

    状态码含义
    500 Internal Server Error客户端请求有效,服务器处理时发生了意外
    503 Service Unavailable服务器无法处理请求,一般用于网站维护状态

    4.服务器回应

    API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以服务端返回值的Content-Type属性应为application/json,同时客户端请求头ACCEPT属性应为application/json。

    发生错误时,不要返回200状态码,这样相当于状态码失去了意义。应该用状态码表示发生的错误,然后在信息里写明错误详情

    提供链接(这个看不懂)

    应用范例

    this.Ctx.ResponseWriter.WriteHeader(http.StatusOK)
    //手动控制HTTP状态码
    this.Ctx.ResponseWriter.Write([]byte("byebye"))
    //手动控制HTTP返回值
    
    beego.Router("/user/:id([0-9]+",&controllers.UserController{},"GET:Get,PUT:Put,DELETE:Delete")
    //同个接口路径不同类型访问导向不同方法
    
    展开全文
  • Restful API 的接口规范

    千次阅读 2022-02-11 16:52:27
    这导致API构架的流行,RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。 rest是Representational State Transfer三个单词的缩写,由Roy Fielding于2000年论文中提出的一种web软件结构风格,注意它...
  • RestfulAPI规范

    2021-02-27 14:56:09
    Restful是目前最流行的API设计规范,用于Web数据接口的设计。 一、动词+宾语 Restful的核心思想就是,客户端发出的数据操作指令都是“动词+宾语”的结构。 如:GET/articles这个接口,GET是动词,articles是宾语...
  • RESTFul规范RESTFul是一种HTTP API接口规范,只要满足的RESTFul规范,即可称为RESTFul API。既然是接口,我们先来了解一下,他和传统的API接口有何不同吧。本文以尽量简单明了的文字来介绍、描述,只讲核心内容,仅...
  • 三、Restful API接口设计规范3.1、协议3.2、路径规则|域名3.3、版本控制3.4、请求类型3.5、传入参数3.5.1、地址栏参数3.5.2、请求body数据3.5.3、请求头3.6、返回格式四、非 Restful Api 的需求4.1、单例型:4.2、...
  • RESTful规范

    2019-08-22 17:32:10
    RESTful 是一种架构的规范与约束、原则,符合这种规范的架构就是 RESTful 架构。 一、动词+宾语 结构 RESTful 的核心思想就是客户端发出的数据操作指令都是“动词+宾语”的结构。比如 GET /articles 这个命令,GET...
  • restful接口设计规范总结

    千次阅读 2021-01-14 03:45:09
    这篇 文章主要是借鉴他人,但是自己很想总结出一套规范一、重要概念:REST,即Representational State Transfer的缩写。我对这个词组的翻译是"表现层状态转化"。Resource(资源) :对象的单个实例。 例如,一只动物。...
  • 1、使用Https协议作为Api和用户的通信协议2、尽量为api分配一个专属的二级域名如:api.kaky.cn3、将版本号放进api的url中会比放在请求头header中更为合适,如:http://api.kaky.cn/v2/4、在Restful架构中,每个网址...
  • RESTful接口规范

    2021-09-03 16:53:24
    本文的主要目的是为了定义系统RESTful接口的相关规范,为研发人员设计业务接口时提供参考和指引。 2 关于REST REST(Representational State Transfer,译为表现层状态转换),是Roy Thomas Fielding在他2000年的博士...
  • RESTfulRESTful API 接口设计规范 | 示例

    万次阅读 多人点赞 2018-10-28 20:57:24
    概念 本质:一种软件架构风格 核心:面向资源设计的API 解决问题: 降低开发的复杂性 提高系统的可伸缩性 例如:设计一套API,为多个终端服务。 设计概念和准则 ...网络上的所有事物都可以被抽象为资源 ...RESTful 与...
  • restful规范(示例代码)

    2021-03-08 21:55:18
    咱们先来谈谈什么是接口?我们常说的一个接口其实就是一个URL。在java和c#中,接口也是一种约束。# 约束继承(实现)了他的类中必须含有IFoo中的方法interface IFoo:def func(self):...主要来看看restful规范有哪些?r...
  • RESTful架构风格规范

    2021-03-03 22:29:37
    REST与RESTful介绍 REST翻译为表现层状态转移(Representational State Transfer, REST),是一种软件架构风格,是Roy Thomas Fielding在他2000年的博士论文中提出的,该结构风格提供一些指导原则和最优方法来帮助我...
  • RESTful设计方法和规范

    2021-01-14 03:45:27
    RESTful设计方法和规范在初步了解了 RESTful 之后,我们接到一项任务,需要为一所学校开发一套师生管理系统,客户要求所开发的系统能在 PC 桌面通过浏览器使用,而且日后还想开发 IOS 和 Android 应用。了解需求之后...
  • restful编码规范

    2020-12-09 18:29:11
    动词 描述 GET(select) 从服务器取出一个/多个资源 POST(create) 在服务器新建一个资源 ...对象范围 使用位置 详细参数 例子 @Api 协议集描述 controller类上 value:URL路径值 description:对ap
  • RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。我以前写过一篇《理解RESTful架构》,探讨如何理解这个概念。 今天,我将介绍RESTful API的设计细节,探讨如何设计一套合理、好用的API。我的主要...
  • Restful API规范及实践

    2019-09-16 10:56:35
    接口尽量使用名词,禁止使用动词,下面是一些例子。 GET /zoos:列出所有动物园 POST /zoos:新建一个动物园 GET /zoos/ID:获取某个指定动物园的信息 PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部...
  • RESTful api接口规范

    万次阅读 多人点赞 2017-01-11 10:40:00
    整体规范建议采用RESTful 方式来实施。   协议 API与用户的通信协议,总是使用HTTPs协议,确保交互数据的传输安全。   域名 应该尽量将API部署在专用域名之下。 https://api.example.com 如果确定API很...
  • 在了解RESTful接口规范之前,我们先来了解一下什么是URI。 1、URI 它是一种通一的资源标志符,大致的意思就是在web上的每一个可用的资源,例如 HTML、图片、程序等都有一个URI进行唯一标识,而这些资源一般对应的是...
  • restful接口规范

    2020-12-23 17:20:59
    规范化请求过程和返回结果 资源描述与视图的松耦合 可提供OpenAPI,便于第三方系统集成,提高互操作性 提供无状态的服务接口,降低复杂度,可提高应用的水平扩展性 二、通用的url语法 URL = scheme'://'...
  • restful Api规范

    千次阅读 2018-07-08 18:16:06
    简介 写接口的开发人员一定不会对它感到陌生,概念啥的就简单介绍一下,主要梳理一下 resful 设计关键内容。...在 Restful 架构中,所有一切都是资源。每一个 URL 都代表着一种资源,而且大部分情况下都是...
  • 一、最原始的接口开发二、优化接口开发(FBV)三、进一步优化,基于CBV模式来开发(CBV)四、RESTful规范RESTful API设计HTTPs规范。域名规范:版本规范。路径规范。method规范。过滤规范。状态码规范错误处理规范返回...
  • restful api规范

    2020-12-05 17:10:40
    restful是目前最流行的API设计规范,用于web数据接口设计 REST有主要两个核心精神: 一、使用resource来当作识别的资源,也就是使用一个URL网址来代表一个Resource 二、同一个Resource则可以有不通的Representations...
  • restful web接口的定义说明: 请求方式:GET、POST、PUT、DELETE 请求路径:/login/?username= 请求参数: username 返回结果:{‘message’:‘ok’}.json 域名 应该尽量将API部署在专用域名之下。 ...
  • RESTFUL API 接口规范

    2020-08-01 13:20:54
    什么是RESTFUL RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用XML格式定义或JSON格式...它首次出现在 2000 年 Roy Fielding 的博士论文中,Roy Fielding是 HTTP 规范的主要编写者之一 RESTf...
  • RESTful发展背景及简介 网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…)。因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 14,325
精华内容 5,730
关键字:

规范restful的例子

友情链接: linux-shell-command.rar