用Python创建API的正确方法-FlyAI

用Python创建API的正确方法

Python3

最后更新 2020-09-27 14:21 阅读 10974

最后更新 2020-09-27 14:21

阅读 10974

Python3

##FlyAI文献翻译
**英文原文：**[：The Right Way to Build an API with Python](https://towardsdatascience.com/the-right-way-to-build-an-api-with-python-cd08ab285f8f)
> **标签**：Python

How can we set up a way to communicate from one software instance to another? It sounds simple, and — to be completely honest — it is.

All we need is an API.

An API (Application Programming Interface) is a simple interface that defines the types of requests (demands/questions, etc.) that can be made, how they are made, and how they are processed.

In our case, we will be building an API that allows us to send a range of GET/POST/PUT/PATCH/DELETE requests (more on this later), to different endpoints, and return or modify data connected to our API.

We will be using the Flask framework to create our API and Postman to test it. In short, we will cover:

>我们如何设置一种从一个软件实例到另一个软件实例的通信方式？这听起来很简单，而且--说实话--确实如此。

>我们需要的只是一个API。

>API（应用程序编程接口）是一个简单的接口，它定义了可以提出的请求（需求/问题等）的类型，如何提出请求，以及如何处理这些请求。

>在我们的案例中，我们将构建一个API，允许我们向不同的端点发送一系列GET/POST/PUT/PATCH/DELETE请求（稍后会有更多介绍），并返回或修改连接到我们API的数据。

>我们将使用Flask框架来创建我们的API，并使用Postman来测试它。总之，我们将涵盖以下内容：

```python
> Setup
  - Our Toy Data
  - Initialize a Flask API
  - Endpoints
  - Running a Local Server
> Writing Our API
  - GET
  - POST
  - 401 Unauthorized
  - PUT
  - DELETE
  - Users Class (summary)
> That's It!
```

**Setup**

Our API will contain two endpoints, users and locations. The former will allow access to our registered user's details, whereas the latter will include a list of cafe locations.

The hypothetical use-case here is of a multi-million cafe bookmarking app, where users open the app and bookmark their favorite cafe’s — like Google Maps, but not useful.

>设置

>我们的API将包含两个端点，用户和地点。前者将允许访问我们的注册用户的详细信息，而后者将包括咖啡馆位置的列表。

>这里的假设用例是一个百万级的咖啡馆书签应用，用户打开应用，将自己喜欢的咖啡馆加入书签--就像谷歌地图一样，但没有用。

**Our Toy Data**

For the sake of simplicity, we are going to store this data in two local CSV files. In reality, you probably want to take a look at something like MongoDB or Google Firebase.

Our CSV files look like this:

>我们的小型数据

>为了简单起见，我们将把这些数据存储在两个本地CSV文件中。在现实中，你可能想看看MongoDB或Google Firebase这样的东西。

>我们的CSV文件是这样的：

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932511892890.png)
User’s data in users.csv. Image by Author.
>user.csv中的用户数据。图片由作者提供。

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932511293251.png)

Location mappings in locations.csv. Image by Author.

You can download users.csv here, and locations.csv here.

>locations.csv中的位置映射。图片由作者提供。

>你可以在这里下载 users.csv，在这里下载 locations.csv。

**Initialize a Flask API**

Now to our Python script, we need to import modules and initialize our API, like so:

>初始化一个Flask API

>现在到我们的Python脚本，我们需要导入模块并初始化我们的API，像这样。

```
from flask import Flask
from flask_restful import Resource, Api, reqparse
import pandas as pd
import astapp = Flask(__name__)
api = Api(app)
```
**Endpoints**

As we already touched on, our API will have two endpoints, users and locations.

The result of this is — if our API was located at www.api.com, communication with the Users class would be provided at www.api.com/users and Locations at www.api.com/locations.

To create an endpoint, we define a Python class (with any name you want) and connect it to our desired endpoint with api.add_resource, like this:

>**端点**

>正如我们已经提到的，我们的API将有两个端点，用户和位置。

>这样做的结果是--如果我们的API位于www.api.com，那么与Users类的通信将在www.api.com/users，而Location则在www.api.com/locations。

>要创建一个端点，我们定义一个Python类(用任何你想要的名字)，然后用api.add_resource将它连接到我们所需的端点，就像这样。

```
class Users(Resource):    
# methods go here    
pass    
api.add_resource(Users, '/users')  # '/users' is our entry point
```

Flask needs to know that this class is an endpoint for our API, and so we pass Resource in with the class definition.

Inside the class, we include our HTTP methods (GET, POST, DELETE, etc.).

Finally, we link our Users class with the /users endpoint using api.add_resource.

Because we want two endpoints, we replicate the logic:

>Flask需要知道这个类是我们的API的一个端点，所以我们将Resource与类定义一起传递进去。

>在这个类里面，我们包含了我们的 HTTP 方法（GET、POST、DELETE 等）。

>最后，我们使用 api.add_resource 将 Users 类与 /users 端点连接起来。

>因为我们想要两个端点，所以我们复制逻辑。

```
class Users(Resource):    
# methods go here    
pass    
class Locations(Resource):    
# methods go here    
pass    
api.add_resource(Users, '/users')  # '/users' is our entry point for Users
api.add_resource(Locations, '/locations')  # and '/locations' is our entry point for Locations
```

**Running a Local Server**

Finally, when we write out our API, we need to test it!

To do this, we need to host our API, which we can do locally by adding app.run to the end of our script like this:

>**运行本地服务器**

>最后，当我们写出我们的API时，我们需要测试它!

>要做到这一点，我们需要对我们的API进行托管，我们可以通过在我们的脚本末尾添加app.run来在本地进行测试，就像这样。

```
if __name__ == '__main__':
    app.run()  # run our Flask app
```
Now, when we run our script, we should see something like this:

>现在，当我们运行我们的脚本时，我们应该看到这样的东西。

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932514716322.png)

Initialization of our localhost server. Image by Author.

Once our server is setup, we can test our API as we build it using Postman, if you haven’t used it before it is the de-facto standard for API testing. And, don’t worry — it’s incredibly simple to use — download Postman from here.

Before going ahead, you can find the full script that we will be building here. If you’re not sure where a code snippet should go, check there!

>我们的localhost服务器的初始化。图片由作者提供。

>一旦我们的服务器设置好了，我们就可以使用Postman来测试我们的API，如果你以前没有使用过它，它是API测试的事实标准。而且，不用担心--使用起来非常简单--从这里下载Postman。

>在开始之前，你可以在这里找到我们将构建的完整脚本。如果你不确定代码片段应该放在哪里，请在这里查看!

**Writing API Methods**

Inside each of our classes, we keep our HTTP methods, GET, POST, and DELETE.

To create a GET method, we use def get(self). POST and DELETE follow the same pattern.

**GET**

The GET method is the simplest. We return all data stored in users.csv wrapped inside a dictionary, like so：

>**编写API的方法**

>在我们的每一个类里面，我们都保存着我们的HTTP方法，GET、POST和DELETE。

>要创建一个GET方法，我们使用def get(self)。POST和DELETE遵循相同的模式。

>**GET**

>GET方法是最简单的。我们返回所有存储在user.csv中的数据，这些数据被包裹在一个字典中，就像这样：

```
class Users(Resources):    
def get(self):    
data = pd.read_csv('users.csv')  # read CSV    
data = data.to_dict()  # convert dataframe to dictionary    
return {'data': data}, 200  # return data and 200 OK code
```
We can then run the script to initialize our API, open Postman and send a GET request to our localhost address (typically http://127.0.0.1:5000)— this is our API entry point.

>然后，我们可以运行脚本来初始化我们的API，打开Postman并向我们的localhost地址（通常是http://127.0.0.1:5000）发送一个GET请求--这是我们的API入口点。

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932514227535.png)

How to send a GET request to our API. Image by Author.
>如何向我们的API发送GET请求。图片由作者提供。

To send a GET request to our API in Postman we:

Select GET from the dropdown

Type the entry point of our API instance + /users (the endpoint)

Hit Send

Check the status code returned by our API (we should see 200 OK)

View our API’s response, which is users.csv in JSON (like a dictionary) format

>要在Postman中向我们的API发送GET请求，我们：

>从下拉菜单中选择GET
输入我们的API实例的入口点+/users(端点)
点击发送
检查我们的API返回的状态代码（我们应该看到200 OK）。
查看我们的API响应，它是JSON格式的user.csv（像一个字典）

**POST**

The POST method allows us to add records to our data. In this case, we will take arguments for usedId, name, and city.

These arguments are passed to our API endpoint as URL parameters, which look like this:

>**POST**

>POST方法允许我们向我们的数据添加记录。在本例中，我们将接受 usedId、name 和 city 的参数，这些参数作为 URL 参数传递给我们的 API 端点。

>这些参数以URL参数的形式传递给我们的API端点，它看起来像这样。

```
http://127.0.0.1:5000/users?userId=abc123&name=The Rock&city=Los Angeles
```

We can specify the required parameters, and then parse the values provided using reqparse — like this:

>我们可以指定所需的参数，然后使用reqparse解析所提供的值--就像这样。

```
parser = reqparse.RequestParser()  # initialize    
parser.add_argument('userId', required=True)  # add arguments    
parser.add_argument('name', required=True)    
parser.add_argument('city', required=True)    
args = parser.parse_args()  # parse arguments to dictionary
```

Let’s break our parser code down:

We initialize our parser with .RequestParser().

Add our arguments with .add_argument([arg_name], required) — note that required=True means that the argument is required in the request. Alternatively, we can add optional arguments with required=False.

Parse our arguments and their values into a Python dictionary using .parse_args().

We can then access the values passed to each argument like we usually would with key-value pairs in a dictionary.

Let’s put those together to add values to our CSV:

>让我们分解一下我们的解析器代码。

>我们用.RequestParser()来初始化我们的解析器。

>用.add_argument([arg_name], required)来添加我们的参数--注意，required=True意味着该参数在请求中是必需的。另外，我们也可以用 required=False 添加可选的参数。

>使用 .parse_args() 将我们的参数和它们的值解析成一个 Python 字典。

>然后，我们可以像通常使用字典中的键值对那样访问传递给每个参数的值。

>让我们把这些放在一起，把值添加到我们的 CSV 中。

```
class Users(Resource):    
def post(self):    
parser = reqparse.RequestParser()  # initialize    
parser.add_argument('userId', required=True)  # add args    
parser.add_argument('name', required=True)    
parser.add_argument('city', required=True)    
args = parser.parse_args()  # parse arguments to dictionary    
# create new dataframe containing new values    
new_data = pd.DataFrame({    
'userId': args['userId'],    
'name': args['name'],    
'city': args['city'],    
'locations': [[]]    
})    
# read our CSV    
data = pd.read_csv('users.csv')    
# add the newly provided values    
data = data.append(new_data, ignore_index=True)    
# save back to CSV    
data.to_csv('users.csv', index=False)    
return {'data': data.to_dict()}, 200  # return data with 200 OK
```
If it’s starting to look a little more confusing — all we’re doing is:

Creating a row of new data new_data from the URL parameters args

Appending it to the pre-existing data

Saving the newly merged data

And, returning data alongside a 200 OK status code.

>如果它开始看起来有点混乱--我们正在做的是：

>从URL参数args中创建一行新的数据new_data
将其添加到已有的数据中
保存新合并的数据
然后，在 200 OK 状态码旁边返回数据

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932513406189.png)

We create a new user by sending a POST request containing userId, name, and city parameters to our /user endpoint. Image by Author.

>我们通过向/user端点发送一个包含userId、名称和城市参数的POST请求来创建一个新用户。图片由作者提供。

We can now send a POST request to create a new user, easy!

>我们现在可以发送一个POST请求来创建一个新用户，非常简单！

**401 Unauthorized**

Our code handles POST requests, allowing us to write new data to users.csv — but what if that user already exists?

For that, we need to add a check. If the userId already exists, we return a 401 Unauthorized code to the user.

>**401 未经批准**

>我们的代码处理POST请求，允许我们向user.csv写入新的数据--但如果该用户已经存在怎么办？

>为此，我们需要添加一个检查。如果userId已经存在，我们就返回一个401 Unauthorized代码给用户。

```
...    
# read our CSV    
data = pd.read_csv('users.csv')    
if args['userId'] in list(data['userId']):    
return {    
'message': f"'{args['userId']}' already exists."    
}, 401    
else:    
# create new dataframe containing new values    
new_data = pd.DataFrame({    
'userId': args['userId'],    
'name': args['name'],    
'city': args['city'],    
'locations': [[]]    
})    
# add the newly provided values    
data = data.append(new_data, ignore_index=True)    
data.to_csv('users.csv', index=False)  # save back to CSV    
return {'data': data.to_dict()}, 200  # return data with 200 OK
```
![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932513868318.png)

If we try to POST again with the userId ‘abc123’, we will return the following 401 Unauthorized status code and message. Image by Author.

Going back to Postman, we can test if our API is functioning by trying to add the same user twice — this time, The Rock received a 401 Unauthorized response.

>如果我们尝试用用户ID'abc123'再次POST，我们将返回以下401 Unauthorized状态代码和消息。图片由作者提供。

>回到Postman，我们可以通过尝试两次添加同一个用户来测试我们的API是否正常工作--这一次，The Rock收到了401 Unauthorized响应。

**PUT**

What if we want to add a cafe to a user? We can’t use POST as this returns a 401 Unauthorized code — instead, we use PUT.

Similar to POST, we need to add if-else logic in the case of the provided userId not existing.

>**PUT**

>如果我们想给用户添加一个咖啡馆呢？我们不能使用POST，因为这将返回一个401 Unauthorized代码--相反，我们使用PUT。

>与POST类似，我们需要在提供的userId不存在的情况下添加if-else逻辑。

```
class Users(Resource):    
def put(self):    
parser = reqparse.RequestParser()  # initialize    
parser.add_argument('userId', required=True)  # add args    
parser.add_argument('location', required=True)    
args = parser.parse_args()  # parse arguments to dictionary    
# read our CSV    
data = pd.read_csv('users.csv')    
if args['userId'] in list(data['userId']):    
# evaluate strings of lists to lists    
data['locations'] = data['locations'].apply(    
lambda x: ast.literal_eval(x)    
)    
# select our user    
user_data = data[data['userId'] == args['userId']]    
# update user's locations    
user_data['locations'] = user_data['locations'].values[0] \    
.append(args['location'])    
# save back to CSV    
data.to_csv('users.csv', index=False)    
# return data and 200 OK    
return {'data': data.to_dict()}, 200    
else:    
# otherwise the userId does not exist    
return {    
'message': f"'{args['userId']}' user not found."    
}, 404
```
Other than a couple of small tweaks to the code, our PUT method is almost identical to POST.

>除了几个小的代码调整，我们的PUT方法和POST几乎是一样的。

Here we use the PUT method to add the cafe with ID 0007 to The Rock’s bookmarked locations. Image by Author.

Back in Postman, our required input parameters have changed. Now, we only need userId and a location to add to the users bookmarked locations.

>这里我们使用PUT方法将ID为0007的咖啡馆添加到The Rock的书签位置。图片由作者提供。

>在Postman中，我们所需的输入参数已经改变了。现在，我们只需要userId和一个位置来添加到用户的书签位置。

**DELETE**

We can also delete records with the DELETE method.

This method is pretty straightforward, we need to specify a userId to remove, and add some if-else logic in the case of a non-existent userId.

So if Jill decides our app is useless and wants to leave, we would send a DELETE request containing her userId.

>**DELETE**

>我们还可以通过DELETE方法来删除记录。

>这个方法很直接，我们需要指定一个要删除的userId，并在userId不存在的情况下添加一些if-else逻辑。

>所以，如果Jill决定我们的应用没有用，想要离开，我们就会发送一个包含她的userId的DELETE请求。

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932513717208.png)

Sending a DELETE request for userId ‘b2c’ deletes Jill’s record from our user data. Image by Author.

We can test this in Postman, and as expected, we return our data without Jill’s record. What if we try and delete a non-existent user?

>为userId'b2c'发送DELETE请求，从我们的用户数据中删除Jill的记录。图片由作者提供。

>我们可以在Postman中进行测试，正如预期的那样，我们返回的数据中没有Jill的记录。如果我们尝试删除一个不存在的用户呢？

![](https://static.leiphone.com/uploads/new/sns/article/202009/1600932513325434.png)

If we DELETE a userId that does not exist, we will receive a 404 Not Found status code and a message explaining that the userId does not exist. Image by Author.

Again, we receive our 404 Not Found and a brief message explaining that the userId was not found.

>如果我们删除一个不存在的 userId，我们将收到一个404 Not Found 状态代码和一条解释 userId 不存在的消息。图片由作者提供。

>同样，我们收到了我们的404 Not Found 和一条简短的消息，解释说找不到 userId。

**Users Class**

That’s all of the parts that make up the Users class, accessed via our /users endpoint. You can find the full script for it here.

After that, we still need to put together the Locations class. This other class should allow us to GET, POST, PATCH (update), and DELETE locations.

Each location is given a unique ID — when a user bookmarks a location, that unique ID is added to their locations list with PUT /users.

The code for this is not that much different from what we wrote in the Users class so that we won't repeat ourselves. However, you can find it alongside the Users class here.

>**用户类别**

>这就是构成Users类的所有部分，通过我们的/users端点访问。你可以在这里找到它的完整脚本。

>之后，我们还需要把Location类放在一起。这个其他类应该允许我们GET、POST、PATCH（更新）和DELETE位置。

>每个位置都被赋予一个唯一的ID--当用户将一个位置作为书签时，这个唯一的ID会通过PUT /users添加到他们的位置列表中。

>这个代码和我们在Users类中写的没有太大区别，所以我们不会重复。不过，你可以在这里和Users类一起找到它。

**That’s It!**

It’s as simple as that. Setting up an API with Flask and Python is incredibly straightforward.

We now have an easy-to-use and standardized method for communicating between different interfaces.

We’ve covered all of the most common request methods — GET, POST, PUT, and DELETE — and a few HTTP status codes too — 200, 401, and 404.

Finally, we’ve learned how to host our API locally and test it with Postman — allowing us to quickly diagnose issues and ensure our API is behaving as intended.

All-in-all, API development is a crucial skill for developers, data scientists, and almost any other tech-inclined role you can imagine.

If you have any questions or ideas for improvement, let me know on Twitter or in the comments below.

I hope you enjoyed the article and thank-you for reading!

>**就是这样！**

>就这么简单。用Flask和Python设置一个API是非常直接的。

>我们现在有了一个易于使用和标准化的方法来在不同的接口之间进行通信。

>我们已经涵盖了所有最常见的请求方法--GET、POST、PUT和DELETE--以及一些HTTP状态码--200、401和404。

>最后，我们已经学会了如何在本地托管我们的API，并使用Postman进行测试--让我们能够快速诊断问题，并确保我们的API按照预期的方式运行。

>总而言之，API开发是开发人员、数据科学家以及你能想象到的几乎所有其他技术型角色的一项重要技能。

>如果你有任何问题或改进的想法，请在Twitter上或在下面的评论中告诉我。

>希望你喜欢这篇文章，谢谢你的阅读!

本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可，转载请附上原文出处链接和本声明。
本文链接地址：https://www.flyai.com/article/710

讨论

500字

表情

发送

删除确认

是否删除该条评论？

取消删除