阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 jQuery.rest 中文API文档

      插件 jQuery.rest 中文API文档

      源码 & 下载

      适用场景

      需要使用 RESTful API 的时候

      插件特点

      一个jQuery插件,可以轻松使用RESTful API

      • 简单
      • 使用jQuery Deferred for Asynchonous链接
      • 基本身份验证支持
      • 有用的错误消息
      • 内存缓存
      • XDomain的跨域请求

      文件大小报告

      • Original: 10314 bytes.
      • Minified: 5920 bytes.
      • Gzipped: 1376 bytes.

      基本用法

      1. 创建一个客户端。
      2. 构建您的API。
      3. 提出要求。

      首先设置您的页面:

      <!-- jQuery -->
      <script src="//ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
      
      <!-- jQuery rest -->
      <script src="http://jpillora.com/jquery.rest/dist/1/jquery.rest.min.js"></script>
      <!-- WARNING: I advise not using this link, instead download and host this library on your own server as GitHub has download limits -->
      
      <script>
        // Examples go here...
      </script>
      

      Hello jquery.rest

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      
      client.foo.read();
      // GET /rest/api/foo/
      client.foo.read(42);
      // GET /rest/api/foo/42/
      client.foo.read('forty-two');
      // GET /rest/api/foo/forty-two/
      

      检索结果 (Uses jQuery’s $.Deferred)

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      
      var request = client.foo.read();
      // GET /rest/api/foo/
      request.done(function (data, textStatus, xhrObject){
        alert('I have data: ' + data);
      });
      
      // OR simply:
      client.foo.read().done(function (data){
        alert('I have data: ' + data);
      });
      

      更多例子

      嵌套资源

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      client.foo.add('baz');
      
      client.foo.read();
      // GET /rest/api/foo/
      client.foo.read(42);
      // GET /rest/api/foo/42/
      
      client.foo.baz.read();
      // GET /rest/api/foo/???/baz/???/
      // ERROR: jquery.rest: Invalid number of ID arguments, required 1 or 2, provided 0
      client.foo.baz.read(42);
      // GET /rest/api/foo/42/baz/
      client.foo.baz.read('forty-two',21);
      // GET /rest/api/foo/forty-two/baz/21/
      

      基本的CRUD

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      
      // C
      client.foo.create({a:21,b:42});
      // POST /rest/api/foo/ (with data a=21 and b=42)
      // Note: data can also be stringified to: {"a":21,"b":42} in this case, see options below
      
      // R
      client.foo.read();
      // GET /rest/api/foo/
      client.foo.read(42);
      // GET /rest/api/foo/42/
      
      // U
      client.foo.update(42, {my:"updates"});
      // PUT /rest/api/42/   my=updates
      
      // D
      client.foo.destroy(42);
      client.foo.del(42);
      // DELETE /rest/api/foo/42/
      // Note: client.foo.delete() has been disabled due to IE compatibility
      

      添加自定义动词

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      client.foo.addVerb('bang', 'PATCH');
      
      client.foo.bang({my:"data"});
      //PATCH /foo/bang/   my=data
      client.foo.bang(42,{my:"data"});
      //PATCH /foo/42/bang/   my=data
      

      基本认证

      var client = new $.RestClient('/rest/api/', {
        username: 'admin',
        password: 'secr3t'
      });
      
      client.add('foo');
      
      client.foo.read();
      // GET /rest/api/foo/
      // With header "Authorization: Basic YWRtaW46c2VjcjN0"
      

      注:window.btoa填充工具如Base64.js将需要此功能在IE6,7,8,9工作

      高速缓存

      var client = new $.RestClient('/rest/api/', {
        cache: 5, //This will cache requests for 5 seconds
        cachableMethods: ["GET"] //This defines what method types can be cached (this is already set by default)
      });
      
      client.add('foo');
      
      client.foo.read().done(function(data) {
        //'client.foo.read' is now cached for 5 seconds
      });
      
      // wait 3 seconds...
      
      client.foo.read().done(function(data) {
        //data returns instantly from cache
      });
      
      // wait another 3 seconds (total 6 seconds)...
      
      client.foo.read().done(function(data) {
        //'client.foo.read' cached result has expired
        //data is once again retrieved from the server
      });
      
      // Note: the cache can be cleared with:
      client.cache.clear();
      

      覆盖选项

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo', {
        stripTrailingSlash: true,
        cache: 5
      });
      
      client.foo.add('bar', {
        cache: 10,
      });
      
      client.foo.read(21);
      // GET /rest/api/foo (strip trailing slash and uses a cache timeout of 5)
      
      client.foo.bar.read(7, 42);
      // GET /rest/api/foo/7/bar/42 (still strip trailing slash though now uses a cache timeout of 10)
      

      花哨的网址

      var client = new $.RestClient('/rest/api/');
      

      假设我们想要创建一个端点 /rest/api/foo-fancy-1337-url/,而不是:

      client.add('foo-fancy-1337-url');
      
      client['foo-fancy-1337-url'].read(42);
      // GET /rest/api/foo-fancy-1337-url/42
      
      这是坏事和丑陋,我们这样做:
      
      client.add('foo', { url: 'foo-fancy-1337-url' });
      
      client.foo.read(42);
      // GET /rest/api/foo-fancy-1337-url/42
      

      查询参数

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      
      client.foo.read({bar:42});
      // GET /rest/api/foo/?bar=42
      
      client.foo.create({ data:7 }, { bar:42 });
      // POST /rest/api/foo/?bar=42 with body 'data=7'
      
      client.foo.read({ data:7 }, { bar:42 });
      // GET has no body!
      // GET /rest/api/foo/?bar=42&data=7
      

      显示API示例

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      client.add('bar');
      client.foo.add('baz');
      
      client.show();
      

      控制台应该说:

      ROOT: /rest/api/
        foo: /rest/api/foo/:ID_1/
          create: POST
          read: GET
          update: PUT
          delete: DELETE
          baz: /rest/api/foo/:ID_1/baz/:ID_2/
            create: POST
            read: GET
            update: PUT
            delete: DELETE
        bar: /rest/api/bar/:ID_1/
          create: POST
          read: GET
          update: PUT
          delete: DELETE
      

      简化 client

      var client = new $.RestClient('/rest/api/');
      
      client.add('forum');
      client.forum.add('post');
      client.forum.post.add('comment');
      

      代替:

      client.forum.post.comment.read(42,21,7);
      client.forum.post.comment.update(42,21,7, {...});
      

      你可以做:

      var comment = client.forum.post.comment;
      comment.read(42,21,7);
      comment.update(42,21,7, {...});
      

      全局客户端示例

      $.client = new $.RestClient('/rest/api/');
      
      // in another file...
      
      $.client.add('foo');
      

      注意:这不是最佳实践,请使用RequireJS,CommonJS或类似的!

      方法覆盖标题

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      client.foo.update(42);
      // PUT /rest/api/foo/42/
      
      client.add('bar', { methodOverride: true });
      client.bar.update(42);
      // POST /rest/api/bar/42/
      // with header 'X-HTTP-Method-Override: PUT'
      

      单资源示例

      var client = new $.RestClient('/rest/api/');
      
      client.add('foo');
      client.foo.add('bar', { isSingle: true });
      client.foo.bar.add('bazz');
      
      client.foo.bar.bazz.read(42, 21);
      // GET /rest/api/foo/42/bar/bazz/21/
      //        'bar' has no id  ^
      

      API

      new $.RestClient( [ url ], [ options ] )

      实例化并返回根资源。下面表示为client。

      client.add( name, [ options ] )

      实现嵌套资源client。在内部,这会做另一个,new $.RestClient 但不是将其设置为root,而是将其作为嵌套(或子)资源添加为当前属性client。

      新创建的嵌套资源 options.verbs 在每个资源上迭代它们和addVerb。

      注意:每个动词的url都设置为""。

      请参阅默认options.verbs 这里。

      client.addVerb( name, method, [ options ] )

      在上面实现一个新的Verb函数属性 client

      注意:name 用作 urlif options.url未设置。

      client.verb( [ id1], …, [ idN], [ data], [ params])

      所有动词都使用此签名。在内部,它们基本上都是调用$.ajax自定义选项,具体取决于父client和options。

      ids必须是字符串或数字。

      data是一个jQuery Ajax Options Object的数据属性。如果ajax.data设置client为此data将延长它。

      params 查询要附加到url的参数

      注意:如果使用无效参数,则会引发有用的错误。

      选项

      该options对象是一个纯JavaScript选项,可能只包含下面列出的属性。

      请参阅此处的默认值

      重要提示:资源和动词都继承了父级的选项!

      高速缓存

      一个数字,表示使用先前缓存的请求的秒数。设置为时0,不存储任何请求。

      cachableMethods

      一个字符串数组,表示可以缓存的HTTP方法类型。是[“GET”]默认。

      verbs

      用作一个普通的对象name到method映射。

      默认verbs对象设置为:

      {
        'create': 'POST',
        'read'  : 'GET',
        'update': 'PUT',
        'delete': 'DELETE'
      }
      

      例如,要将更新的默认行为从使用PUT更改为使用POST,请将verbs属性设置为{ update: ‘POST’ }

      url

      表示给定资源或动词的URL的字符串。

      注意:url不会被继承,如果没有显式设置,则该名称将用作URL。

      stringifyData

      何时true,将通过所有POST数据JSON.stringify(IE <= 8所需的polyfill)。

      stripTrailingSlash 何时true,将从URL中删除尾部斜杠。

      用户名和密码 如果同时设置了用户名和密码,则所有ajax请求都将添加“授权”标头。编码使用btoa(polyfill required not non webkit)。

      ajax

      在jQuery的阿贾克斯选项对象

      methodOverride

      当true请求(不包括HEAD和GET)成为POST请求时,所选方法将被设置为标题:X-HTTP-Method-Override。对于不支持某些HTTP方法的客户端和/或服务器很有用。

      request

      用于执行请求的函数(必须返回jQuery Deferred)。默认情况下,它是:

      request: function(resource, options) {
        return $.ajax(options);
      }
      

      isSingle

      当true资源被视为单身时:

      请参见Singleton资源示例

      autoClearCache

      如果false,非超高速缓存请求(PUT,POST或者DELETE-那些没有cachableMethods)将不会自动清除缓存请求的条目。

      注意:想要更多选择?打开上面的新功能问题。

      概念概述

      这个插件由嵌套的“Resource”类组成。资源包含选项,子资源和子动词。动词是执行各种HTTP请求的函数。无论new $.RestClient和client.add资源的建设新的实例,但前者会造成不附带任何动词根资源,而后者将创建子资源与它的所有options.verbs连接。

      由于每个资源都可以拥有自己的一组选项,因此在实例化时,选项是从父资源继承的,允许在子资源上使用一组默认选项和自定义选项。

      官方介绍

      源码解析

      参考引用

      目录
      目录