了解 API 及其结构

Source: Dev.to

什么是 API？

API 是 Application Programming Interface（中文：应用程序编程接口）的缩写。
基本上，API 是一种系统之间相互通信的方式，以有组织的方式并遵循预定义的规则交换信息。如果一个系统想要获取另一个系统的数据、发送信息、创建或更新某些内容，API 就充当这座桥梁。

当我们谈论 REST API 时，它们使用 HTTP/HTTPS 进行通信，这正是浏览器使用的协议。所有操作都是通过 URL（称为 端点）完成的。

• 端点（Endpoint）：提供 API 服务的地址。
• 请求 → 响应（Request → Response）：API 接收请求并返回数据、确认或错误，并始终附带 状态码（例如：200 – OK）。

常见的 HTTP 方法

数据格式

大多数现代 API 使用 JSON 作为信息交换格式：

{
  "exemplo": "valor",
  "lista": [1, 2, 3]
}

JSON 轻量、易读，并且几乎可以在所有语言中良好工作。

请求头（Headers）

请求头携带 API 处理请求所需的额外信息，例如：

• 内容类型 (Content-Type: application/json)
• 身份验证令牌
• 语言 (Accept-Language)
• 权限信息

如果缺少正确的请求头，很多 API 甚至不会允许访问。

身份验证

并非所有 API 都是公开的；大多数都需要权限验证。常用的机制包括：

• API Key
• Bearer Token
• JWT（JSON Web Token）
• OAuth2

版本控制

API 会随时间演进，因此在 URL 中加入版本号是常见做法：

/api/v1/clientes

使用 Spring Boot 的简单 API 示例

可以通过 Spring Initializr 快速创建一个 API。

基本步骤

1. 访问 Spring Initializr，生成一个包含所需依赖（例如 Spring Web）的项目。
2. 在你的 IDE 中导入该项目。
3. 创建一个 REST 控制器：

// src/main/java/com/exemplo/DemoController.java
package com.exemplo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/api/v1/hello")
    public String hello() {
        return "Olá, mundo!";
    }
}

4. 运行应用（./mvnw spring-boot:run 或通过 IDE），然后访问端点 http://localhost:8080/api/v1/hello。

有用链接

• Spring Initializr: https://start.spring.io
• 作者的 LinkedIn 个人主页: (链接未提供)