VPS推荐

应用程序编程接口API设计最佳实践

Pinterest LinkedIn Tumblr

应用程序编程接口(API)是中间件,当您运行移动应用程序(如Facebook)时,它使用API连接到远程数据。API是现代IT行业中交换数据的标准方式,因为它们提供了许多好处。例如,移动、桌面和Web应用程序可以共享由API获取的数据。API还加快了与第三方应用程序集成的内部软件开发。在大多数情况下,您将使用服务器端脚本语言(如PHP、Python或Node.js)开发API。本指南重点介绍创建开发人员友好型应用程序编程接口API设计最佳实践。

应用程序编程接口API设计最佳实践
应用程序编程接口API设计最佳实践

1. 使用JSON数据交换格式

接受并响应使用最常见的数据交换格式的API请求。虽然一些遗留API仍然使用可扩展标记语言(XML),但JavaScript对象表示法(JSON)格式更紧凑,大多数开发人员都认为它既适合人类阅读,也适合机器阅读,如下所示。

{

  "data": {

    "product_id": 123,

    "product_name": "SPORTS BIKE",

    "retail_price": 2499.36,

    "remaining_stock": 786

  }

}

以下代码是上述JSON数据在XML中的等效项。

<data>

  <product_id>123</product_id>

  <product_name>SPORTS BIKE</product_name>

  <retail_price>2499.36</retail_price>

  <remaining_stock>786</remaining_stock>

</data>

正如您所看到的,JSON比XML更美观,因此在开发新API时请考虑使用它。此外,大多数编程语言(如PHP)都提供了不同的工具来解析和格式化JSON数据,无疑可以更快地访问数据。

2. 在URL路径中使用名词而不是动词

在创建API URL端点时,请考虑使用名词而不是动词。然后,接受不同的HTTP请求方法(GET、POST、PUT和DELETE)来执行不同的数据操作。这使URL更短、更整洁。同时,它最小化了为单个资源完成CRUD(创建、读取、更新和删除)操作所需的URL总数。

为了更好地说明这一点,请考虑以下使用URL中的动词的API端点。

<https://www.example.com/api/v1/create_product>

<https://www.example.com/api/v1/get_products>

<https://www.example.com/api/v1/update_product>

<https://www.example.com/api/v1/delete_product>

您可以将上面的URL整齐地合并为单个资源路径,如下所示。

<https://www.example.com/api/v1/products>

然后,API消费者可以使用不同的HTTP动词通过执行以下请求检索、提交、更新和删除数据。

  • 检索产品: GET <https://www.example.com/api/v1/products>
  • 创建产品: POST <https://www.example.com/api/v1/products>
  • 更新产品: PUT <https://www.example.com/api/v1/products/{product_id}>
  • 删除产品: DELETE <https://www.example.com/api/v1/products/{product_id}>

3. 使用正确的HTTP状态代码回应

请考虑使用不同的超文本传输协议(HTTP)状态代码来向客户端的请求发出响应,如下所示。

  1. GET https://www.example.com/api/v1/products 响应: 200 OK
  2. PUT https://www.example.com/api/v1/products/{product_id} 响应: 200 OK
  3. POST https://www.example.com/api/v1/products 响应: 201 Created
  4. DELETE https://www.example.com/api/v1/products/{product_id} 响应: 204 No Content

此外,在返回错误时,使用以下HTTP状态代码。

  1. 服务器上找不到资源 404 Not Found
  2. 认证失败。用户名、密码或访问令牌不正确。 401 Unauthorized
  3. 授权失败。当用户已经经过适当的身份验证但没有正确的权限访问资源时使用此错误。 403 Forbidden
  4. 错误请求。来自客户端的错误。例如,数据验证错误。 400 Bad Request
  5. 与服务器相关的错误,包括数据库失败。 500 Internal Server Error

此外,即使在遇到错误并返回HTTP状态代码后,您也应该告知最终用户发生问题的确切原因。例如,在以JSON格式返回错误时,可以包含:

HTTP状态代码。

自定义错误代码。

简短的标题。

详细的人类可读消息,解释问题发生的原因。

以下是一些错误消息的示例。

  1. 认证错误 { "errors": { "http_status_code": 401, "title": "Invalid Login", "message": "The username/password is incorrect." "custom_error_code": 401.1 } }
  2. 验证错误 { "errors": { "http_status_code": 400, "title": "Validation Error", "message": "The 'product_name' field is required." "custom_error_code": 400.1 } }
  3. 授权错误 { "errors": { "http_status_code": 403, "title": "Unauthorized", "message": "You're not authorized to access this resource." "custom_error_code": 403.1 } }

4. 保护API端点

除非您正在创建一个不需要用户登录的公共可用API,否则您必须在API端点中使用某种形式的身份验证和授权。

以下是一些常见的API身份验证和授权协议。

1. 基本身份验证

基本身份验证是基于用户名和密码的简单身份验证方案。在请求API资源时,客户端将用户名和密码编码为Base64字符串,并将其包含在Authorization请求头中。服务器在响应请求之前对其进行解码,以便验证凭据。

以下是基本身份验证的示例请求。

GET <https://www.example.com/api/v1/products>

Authorization: Basic base64encodedstring

以下是如何使用PHP进行基本身份验证的示例代码。

<?php

$username = "username";

$password = "password";

$authString = $username . ":" . $password;

$authString = base64_encode($authString);

$headers = array(

 "Authorization: Basic " . $authString

);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "<https://www.example.com/api/v1/products>");

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

curl_close($ch);

?>

2. OAuth 2.0

OAuth 2.0是一种标准的授权框架,用于在应用程序之间共享用户的资源。在OAuth 2.0中,客户端必须首先请求身份验证令牌。然后,客户端使用身份验证令牌请求访问令牌。最后,客户端使用访问令牌访问API资源。

以下是如何使用OAuth 2.0进行身份验证的示例请求。

GET <https://www.example.com/api/v1/products>

Authorization: Bearer access_token

以下是如何使用PHP进行OAuth 2.0身份验证的示例代码。

<?php

$access_token = "access_token";

$headers = array(

 "Authorization: Bearer " . $access_token

);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "<https://www.example.com/api/v1/products>");

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

curl_close($ch);

?>

3. API密钥

API密钥是一种简单的身份验证机制,其中客户端使用单个字符串身份验证其请求。API密钥可以在API管理控制台中生成,并分配给每个API消费者。

以下是如何使用API密钥进行身份验证的示例请求。

GET <https://www.example.com/api/v1/products>

X-API-Key: api_key

以下是如何使用Python进行API密钥身份验证的示例代码。

import requests

url = "<https://www.example.com/api/v1/products>"

headers = {"X-API-Key": "api_key"}

response = requests.get(url, headers=headers)

print(response.content)

5. 返回元数据

在响应API请求时,包括从请求资源返回的当前页码(page)、页面大小(per_page)和总记录数(count)等元数据。如下所示。

{

  "data" : {

    "product_id" : 123,

    "product_name" : "SPORTS BIKE",

    "retail_price" : 2499.36,

    "remaining_stock" : 786

  },

  ...

"meta" : {

    "page" : 1,

    "per_page" : 3,

    "total_pages" : 5,

    "count" : 15

  }

}

6. 在API端点中接受排序参数

允许API消费者在URL中指定排序参数以按升序排序数据。另一方面,可以在字段名称前缀加上减号-,以按降序排序数据。以下是几个示例,说明排序URL应该是什么样子的。

  • product_name升序排序数据。 GET <https://www.example.com/api/v1/products?sort=product_name>
  • product_name降序排序数据。 GET <https://www.example.com/api/v1/products?sort=-product_name>
  • retail_price升序排序数据。 GET <https://www.example.com/api/v1/products?sort=retail_price>
  • retail_price降序排序数据。 GET <https://www.example.com/api/v1/products?sort=-retail_price>
  • retail_price然后按product_name升序排序数据。 GET <https://www.example.com/api/v1/products?sort=retail_price,product_name>
  • retail_price然后按product_name降序排序数据。 GET <https://www.example.com/api/v1/products?sort=-retail_price,-product_name>

7. 允许用户过滤和搜索API数据

与排序数据类似,您的API应提供一种使用URL参数过滤数据的方法。例如,要通过名称搜索项目,API消费者可以进行以下请求。

GET  <https://www.example.com/api/v1/products?search=sample_keyword>

您还可以允许用户在多个字段名称上指定关键字,如下所示。

GET  <https://www.example.com/api/v1/products?category_id=7,is_active=Y>

此外,有时最终用户可能不想检索所有字段名。在这种情况下,允许他们使用field参数指定要检索的列,如下所示。

GET  <https://www.example.com/api/v1/products?fields=product_name,category_name,retail_price>

GET  <https://www.example.com/api/v1/products?fields=product_name>

GET  <https://www.example.com/api/v1/products?fields=category_name>

8. 对API端点进行速率限制

为了避免滥用服务器资源,请对API进行速率限制。例如,您可以指定单个用户在一小时、一天或一个月内可以发出的请求总数。

超过该限制的任何帐户都应失败,并显示以下HTTP状态代码。

429 Too Many Requests

限制API端点的速率可提高其可用性,并消除任何拒绝服务(DOS)攻击的可能性。您可以使用不同的技术来实现这一点,包括Redis,它的效果非常好。

9. 对您的API设计进行版本控制

在开发API时,您将进行不同的更改,甚至在向公众发布之后也会进行更改,以改进它并提供更多功能。您可以通过电子邮件向最终用户传达这些更改,但是您必须对API进行版本控制,以避免在每次更新后破坏客户端应用程序。

在新版本发布后,始终支持至少一个先前版本,并在转换所有使用者之后将其弃用。为了支持此功能,请在您的API URL中包含版本标识符,如下所示。

  • 版本1: <https://www.example.com/api/v1>
  • 版本2: <https://www.example.com/api/v2>
  • 版本3: <https://www.example.com/api/v3>

10. 在云中托管您的API设计

您可以将API部署在搬瓦工Vultr等云计算服务器上。