python RESTful API框架:Eve 快速入门，pythonrestful


Eve是一款Python的REST API框架，用于发布高可定制的、全功能的RESTful的Web服务，帮你轻松创建和部署API，本文翻译自Eve官方网站：
http://python-eve.org/quickstart.html#database-interlude

Eve 快速入门：
渴望开始吗？这个页面将提供Eve一个很好的介绍。在这之前假设：
你已经安装好了Eve。如果你还没有，可以点击到安装页面。
已经安装了MongoDB。
并且MongoDB 已经运行了。
一个最小的应用
一个最小的Eve应用，看起来是这样的：

from eve import Eve
app = Eve()

if __name__ == '__main__':
    app.run()

然后保存为run.py，接着创建一个新的文档包含已经内容：

DOMAIN = {'people': {}}

接着保存为settings.py，并且放在run.py相同的文件夹下。
这是Eve的配置文件，一个标准的python模块，这个文件告诉了Eve你的API包含了一个可访问的资源，people。

现在你已经准备好启动你的API了。

$ python run.py
 * Running on http://127.0.0.1:5000/

现在你已经可以使用这个API了：

$ curl -i http://127.0.0.1:5000
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 82
Server: Eve/0.0.5-dev Werkzeug/0.8.3 Python/2.7.3
Date: Wed, 27 Mar 2013 16:06:44 GMT

恭喜，你的GET请求已经得到了一个很好的响应返回，让我们看看这个有效负载：

{
    "_links": {
        "child": [
            {
                "href": "people",
                "title": "people"
            }
        ]
    }
}

API接入点遵循着HATEOAS（超媒体即状态应用引擎）原则和规定API资源访问信息，在我们的例子中只提供了一个可用child的资源，这里是people。

现在尝试请求people：

$ curl http://127.0.0.1:5000/people
{
    "_items": [],
    "_links": {
        "self": {
            "href": "people",
            "title": "people"
        },
        "parent": {
            "href": "/",
            "title": "home"
        }
    }
}

这次我们也得到了一个_items 表，_links 相对于是被访问的资源，所以你得到了父资源链接（主页）和资源本身。

默认情况下Eve 的APIs是只读的：

$ curl -X DELETE http://127.0.0.1:5000/people
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method DELETE is not allowed for the requested URL.</p>

这是因为我们还没有在settings.py中规定任何的数据库细节，所以Eve会在无法索引到任何people表实际的内容（甚至可能不存在）时无缝得提供一个空的资源，因为我们不想让API的使用者down（不知道译成什么好…）。
插入数据库
让我们通过增加下面几行到setting.py来连接数据库：

# 根据编辑需要，让我们使用本地mongod实例

# 需要注意的是MONGO_HOST 和 MONGO_PORT很有可能会无效，因为默认存在本地系统的值。

MONGO_HOST = 'localhost'
MONGO_PORT = 27017
MONGO_USERNAME = 'user'
MONGO_PASSWORD = 'user'
MONGO_DBNAME = 'apitest'

由于MongoDB便捷性，我们不需要真正得去创建数据表，实际上我们甚至不需要创建数据库：GET 请求空的或不存在的数据库是会返回正确（200 OK会得到一个空集合（表））；DELETE/PATCH/PUT会得到适当的响应（404 Not Found），POST请求会创建所需的数据库或表。然而这样的自动管理的数据库会执行得非常差，因为缺少了索引和任何形式的优化。
一个更复杂的应用
到目前为止我们的API都是只读的，让我们能够全面得进行CRUD（增加(Create)、读取(Retrieve)（重新得到数据）、更新(Update)和删除(Delete)）运作：

# 授权资源、数据库  读 (GET), 插入 (POST) and 删除 DELETE
# (如果你省略这行, API将默认是 ['GET'] 和 提供只读权限访问端点).
# RESOURCE资源，METHODS方法

RESOURCE_METHODS = ['GET', 'POST', 'DELETE']

# 允许 读 (GET), 编辑 (PATCH), 替换 (PUT) 和删除 个人项目 items  (默认访问项目是只读).
# ITEM 项目

ITEM_METHODS = ['GET', 'PATCH', 'PUT', 'DELETE']

当ITEM_METHODS 列表中的方法授权给项目端点(/people/)时RESOURCE_METHODS表中的方法才授权资源端点(/people)。都设置则会有一个全局作用域并使所有的端点都有效。然而你也可以启用或者禁用单个端点的HTTP方法等级，我们很快就能看到。
由于我们允许了编辑了，我们也希望让数据可以进行合适验证。让我们为people资源定义一种模式。

schema = {
  # 模式定义, 基于 Cerberus 语法. 核实 Cerberus 项目细节在
    # (https://github.com/nicolaiarocci/cerberus)。

    'firstname': {
        'type': 'string',
        'minlength': 1,
        'maxlength': 10,
    },
    'lastname': {
        'type': 'string',
        'minlength': 1,
        'maxlength': 15,
        'required': True,
        # 这个DEMO的目的是讨论硬约束
        # 'lastname' 是一个 API 条目标记, 所以我们需要它独一无二。

        'unique': True,
    },
    # 'role' 是一张表，和只能是allowed中的值
    'role': {
        'type': 'list',
        'allowed': ["author", "contributor", "copy"],
    },
        # 一种嵌入式固定类型的字典。
    'location': {
        'type': 'dict',
        'schema': {
            'address': {'type': 'string'},
            'city': {'type': 'string'}
        },
    },
    'born': {
        'type': 'datetime',
    },
}

更多的信息验证请看 数据有效性。

现在让我们讨论下我们想进一步定制端点的people，我们想：
设置一项的标题为person
增加一个额外的自定义项端点在/people/
覆盖默认缓存控制指令
禁用people 端点的DELETE（设置全局变量）

这里是完整得展示setting.py文件更新中people的定义：

people = {
    # 'title'用于项目链接。默认资源标题减去最后 复数 's' (在大部分情况下工作正常，而不是‘people’)
    'item_title': 'person',

        # 根据标准项目接入点是定义成'/people/<ObjectId>'。
    #. 我们让它不可更改 和我们也启动一个额外的只读接入点 ，这个方法也能让消费者执行GET请求'/people/<lastname>'。

    'additional_lookup': {
        'url': 'regex("[\w]+")',
        'field': 'lastname'
    },

    # 我们决定对这个资源覆盖全局变量缓存控制准则。
    'cache_control': 'max-age=10,must-revalidate',
    'cache_expires': 10,

    # most global settings can be overridden at resource level
    'resource_methods': ['GET', 'POST'],

    'schema': schema
}

最后我们更新域定义：

DOMAIN = {
    'people': people,
}

保存setting.py 和启动 run.py。现在我们可以在people端点插入文档了：

$ curl -d '[{"firstname": "barack", "lastname": "obama"}, {"firstname": "mitt", "lastname": "romney"}]' -H 'Content-Type: application/json'  http://127.0.0.1:5000/people
HTTP/1.0 201 OK

我们也可以更新和删除项目（但不能是整个资源，因为我们禁用了）。我们也可以执行GET请求获取这个新的lastname端点：

$ curl -i http://127.0.0.1:5000/people/obama
HTTP/1.0 200 OK
Etag: 28995829ee85d69c4c18d597a0f68ae606a266cc
Last-Modified: Wed, 21 Nov 2012 16:04:56 GMT
Cache-Control: 'max-age=10,must-revalidate'
Expires: 10
...
{
    "firstname": "barack",
    "lastname": "obama",
    "_id": "50acfba938345b0978fccad7"
    "updated": "Wed, 21 Nov 2012 16:04:56 GMT",
    "created": "Wed, 21 Nov 2012 16:04:56 GMT",
    "_links": {
        "self": {"href": "people/50acfba938345b0978fccad7", "title": "person"},
        "parent": {"href": "/", "title": "home"},
        "collection": {"href": "people", "title": "people"}
    }
}

缓存准则和项目标题符合我们新的设置。请看产品特性获取特性完整列表和更多的使用示例。

后记：
所有的例子和代码片段都来自Live demo，这是一个全功能的API，你可以使用到自己的实验和生活实例或本地（你也可以使用实例应用来填充或重置数据库）。

相关内容