TastyPie Restful API使用文档

Tastypie Restful-API

Restful API通过使用HTTP的Method关键字完成了前端和数据库数据的交互，实现了一套比较标准的访问接口，此文主要用于描述基于TastyPie实现的Restful API的使用指南。主要分为增删查改四个部分。

元

这个链接用于获取API的相关信息，会给出所有的可用接口以及相关接口的语法说明。
示例：http://uc.dreamlabchina.com/api/v1/

基础知识：

• list_endpoint
  用于获取列表数据，如：http://uc.dreamlabchina.com/api/v1/block/
  另外在list的meta中会返回这个资源的详细描述信息
• detail_endpoint
  用于获取某个元素的详细信息，如：http://uc.dreamlabchina.com/api/v1/block/{id}/

增

METHOD：POST
访问地址：list_endpoint, detail_point
参数说明：
JSON类型数据，具体可以参考查章节返回的数据格式 (id 和 resource_uri不用填）
返回说明：
正确的话会返回状态码 201 CREATED
错误的话会返回其他错误

特别说明：
默认建议访问list_endpoint,会自动生成ID，如果使用detail_endpoint则会使用自定义ID
如果需要新增foreign_key一类的字段，请使用如下形式：

ToOneField:  user:"/api/v1/user/1/"
ToManyField：users:["/api/v1/user1", "/api/v1/user/2"]

ajax请求示例：

$.ajax({
  url: 'http://uc.dreamlabchina.com/api/v1/block/',
  data: JSON.stringify({'address':'TEST', 'name':'TEST'}),
  method: 'POST',
  dataType: 'json',
  contentType: 'application/json',
  complete: function (xhr, textStatus) {
    console.log("complete");
    console.log(textStatus);
    console.log(xhr.status);
    console.log(xhr.getResponseHeader('Location')); //resource uri.
  }
});

删

METHOD：DELETE
访问地址：detail_endpoint, list_endpoint
参数说明：
无需参数
返回说明：
删除成功返回：Status 204 NO CONTENT
如果被删除东西不存在返回：404 NOT FOUND
其他返回其他错误

特别说明：
访问detail_endpoint会删除当前entry，访问list_endpoint会删除所有enties

ajax请求示例：

$.ajax({
  url: 'http://uc.dreamlabchina.com/api/v1/block/9/',
  method: 'DELETE',
  dataType: 'json',
  contentType: 'application/json',
  complete: function (xhr, textStatus) {
    console.log("complete");
    console.log(textStatus);
    console.log(xhr.status);
  }
});

查

METHOD：GET
访问地址：detail_endpoint, list_endpoint
参数说明：
支持filter，order_by, 具体可以参考django的过滤条件

• 属性访问（prop）

  ex：

  "objects": [
   {
    "area": "124.17",
    "houseowner": [],
    "id": 1,
    "no": "301",
    "resource_uri": "/api/v1/house/1/",
    "unit": {
      "build": {
        "block": {
          "address": "南昌市红谷滩新区红谷滩中大道1568号",
          "build_count": 0,
          "id": 1,
          "name": "红谷凯旋",
          "resource_uri": "/api/v1/block/1/"
        },
        "floor_count": 0,
        "id": 1,
        "no": 1,
        "resource_uri": "/api/v1/build/1/"
      },
      "id": 1,
      "no": 1,
      "resource_uri": "/api/v1/unit/1/"
    }
  }...]

  在url上访问house的属性可以直接使用，比如 no, area
  如果需要访问unit的属性则需要使用双下划线连接，比如 unit__no
  访问build的属性则是 unit__build__no

• filter:
  filter是通过在url后附加条件来完成的，定义如下prop__filtertype=value
  其中filtertype主要有以下类型：

  • exact 精确对比，默认为此类型，例如： no__exact=705, no=705
  • iexact 与上面的相同，但是忽略大小写
  • contains 包含，例如：no__contains=5
  • startswith, endswith 开始，结束
  • in 用于在某个序列的查询，例如：no__in=705,706

  • filter in to_many fields.

    • id in:

      mf__id=n //will filter all mf contains id=n

    • id in OR

      mf__id__in=n1, n2 //will filter all mf contains id=n1 OR id=n2

    • id in AND

      mf__id=n1&mf__id=n2 //will filter all mf contains id=n1 AND id=n2

• order_by:
  可以在url上面增加order_by来实现排序功能，order_by=prop (prop的访问方法见上面 属性访问 节点, 默认位正序排列，需要逆序的时候在prop前面加上-，例如 order_by=-prop

改

METHOD: PUT PATCH
访问地址: detail_endpoint
参数说明:

• PUT
  完整更新，需要传入完整的数据，和GET返回的数据结构保持一致
• PATCH
  部分更新，可以只传入需要更新的字段

返回说明

• PUT
  更新成功返回 Status 204 NO CONTENT
• PATCH
  更新成功返回 Status 202 ACCEPTED

特别说明
如更改关联字段应该想查章节的filter条件一样写。

ajax请求示例:

$.ajax({
  url: 'http://uc.dreamlabchina.com/api/v1/block/8/',
  method: 'PATCH',
  data: JSON.stringify({'build_count':10}),
  dataType: 'json',
  contentType: 'application/json',
  complete: function (xhr, textStatus) {
    console.log("complete");
    console.log(textStatus);
    console.log(xhr.status);
  }
});

code snippets

• create new store

  {
    "addr": "TEST_ADDR",
    "email": "a@b.com",
    "hotline": "02110001000",
    "logo_pic": "/api/v1/store_storepic/27/",
    "logo_url": null,
    "name": "测试_美食",
    "owner": "/api/v1/user/1/",
    "storeinfo": {
      "comment_url": null,
      "delivery": null,
      "info_url": "http://test.url",
      "order_url": null,
      "storeads": null,
      "storeads_seq": null
    },
    "title": "美食店",
    "web_url": ""
  }

• create goods

  {
    "desc": "测试美食_1",
    "detail_url": "test_detail_url",
    "goods_id": "1361",
    "goodsdetail": {
      "adv": "TEST1",
      "avail_time": "8|20|2|2#",
      "class_name": "goods",
      "detail": "TEST",
      "detail_pic_url": "test_link",
      "has_invoice": 0,
      "payed_num": 0,
      "remain_count": 0,
      "size": "pic",
      "type_name": "service"
    },
    "icon": "/api/v1/store_storepic/8/",
    "on_sale": 1,
    "pics": ["/api/v1/store_storepic/8/","/api/v1/store_storepic/7/"],
    "pics_seq": "8,7",
    "price": "0.01",
    "storeinfo": "/api/v1/store_storeinfo/7/",
    "tags": ["/api/v1/store_goodstag/6/"],
    "tags_seq": "6"
  }