Aplicación práctica de API RESTful
Diseño de API de gestión de usuarios
Diseñemos una API completa de sistema de gestión de usuarios; este es el escenario de aplicación más común.
Diseño de endpoints de API
// 用户相关操作
GET /api/users # 获取用户列表
GET /api/users/{id} # 获取特定用户
POST /api/users # 创建新用户
PUT /api/users/{id} # 更新用户信息
DELETE /api/users/{id} # 删除用户
// 用户订单相关操作
GET /api/users/{id}/orders # 获取用户的订单列表
POST /api/users/{id}/orders # 为用户创建订单
GET /api/orders/{orderId} # 获取特定订单详情Operaciones CRUD completas
1. Crear usuario (Create)
// 请求
POST /api/users
Content-Type: application/json
{
"name": "王五",
"email": "wangwu@example.com",
"phone": "13800000000",
"address": {
"city": "上海",
"street": "南京路100号"
}
}
// 成功响应(状态码:201 Created)
{
"success": true,
"data": {
"id": 125,
"name": "王五",
"email": "wangwu@example.com",
"phone": "13800000000",
"address": {
"city": "上海",
"street": "南京路100号"
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:00:00Z"
},
"message": "用户创建成功"
}2. Leer usuario (Read)
// 获取用户列表
GET /api/users?page=1&limit=5&sort=createdAt&order=desc
// 响应(状态码:200 OK)
{
"success": true,
"data": [
{
"id": 125,
"name": "王五",
"email": "wangwu@example.com",
"createdAt": "2024-01-15T10:00:00Z"
},
{
"id": 124,
"name": "李四",
"email": "lisi@example.com",
"createdAt": "2024-01-15T09:00:00Z"
}
],
"pagination": {
"currentPage": 1,
"totalPages": 3,
"totalItems": 15,
"itemsPerPage": 5
}
}
// 获取特定用户
GET /api/users/125
// 响应
{
"success": true,
"data": {
"id": 125,
"name": "王五",
"email": "wangwu@example.com",
"phone": "13800000000",
"address": {
"city": "上海",
"street": "南京路100号"
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:00:00Z"
}
}3. Actualizar usuario (Update)
// 请求
PUT /api/users/125
Content-Type: application/json
{
"name": "王五",
"email": "wangwu.new@example.com",
"phone": "13900000000",
"address": {
"city": "深圳",
"street": "科技园路200号"
}
}
// 响应(状态码:200 OK)
{
"success": true,
"data": {
"id": 125,
"name": "王五",
"email": "wangwu.new@example.com",
"phone": "13900000000",
"address": {
"city": "深圳",
"street": "科技园路200号"
},
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T11:30:00Z"
},
"message": "用户信息更新成功"
}4. Eliminar usuario (Delete)
// 请求
DELETE /api/users/125
// 响应(状态码:200 OK)
{
"success": true,
"message": "用户删除成功"
}
// 如果用户不存在(状态码:404 Not Found)
{
"success": false,
"error": {
"code": "USER_NOT_FOUND",
"message": "用户不存在"
}
}Manejo de errores
Error de validación de datos
// 请求(邮箱格式错误)
POST /api/users
{
"name": "",
"email": "invalid-email",
"phone": "123"
}
// 响应(状态码:400 Bad Request)
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "数据验证失败",
"details": [
{
"field": "name",
"message": "姓名不能为空"
},
{
"field": "email",
"message": "邮箱格式不正确"
},
{
"field": "phone",
"message": "手机号格式不正确"
}
]
}
}Error de recurso no encontrado
// 请求
GET /api/users/999
// 响应(状态码:404 Not Found)
{
"success": false,
"error": {
"code": "USER_NOT_FOUND",
"message": "用户不存在"
}
}Llamar a la API con JavaScript
Ejemplo
// Llamar a la API RESTful usando fetch API
// 1. Obtener la lista de usuarios
async function getUsers() {
try {
const response = await fetch('/api/users');
const result = await response.json();
if (result.success) {
console.log('Lista de usuarios:', result.data);
} else {
console.error('Error al obtener:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 2. Crear un nuevo usuario
async function createUser(userData) {
try {
const response = await fetch('/api/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userData)
});
const result = await response.json();
if (result.success) {
console.log('Usuario creado con éxito:', result.data);
} else {
console.error('Error al crear:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 3. Actualizar información del usuario
async function updateUser(userId, userData) {
try {
const response = await fetch(`/api/users/${userId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userData)
});
const result = await response.json();
if (result.success) {
console.log('Usuario actualizado con éxito:', result.data);
} else {
console.error('Error al actualizar:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 4. Eliminar usuario
async function deleteUser(userId) {
try {
const response = await fetch(`/api/users/${userId}`, {
method: 'DELETE'
});
const result = await response.json();
if (result.success) {
console.log('Usuario eliminado con éxito');
} else {
console.error('Error al eliminar:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 1. Obtener la lista de usuarios
async function getUsers() {
try {
const response = await fetch('/api/users');
const result = await response.json();
if (result.success) {
console.log('Lista de usuarios:', result.data);
} else {
console.error('Error al obtener:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 2. Crear un nuevo usuario
async function createUser(userData) {
try {
const response = await fetch('/api/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userData)
});
const result = await response.json();
if (result.success) {
console.log('Usuario creado con éxito:', result.data);
} else {
console.error('Error al crear:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 3. Actualizar información del usuario
async function updateUser(userId, userData) {
try {
const response = await fetch(`/api/users/${userId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userData)
});
const result = await response.json();
if (result.success) {
console.log('Usuario actualizado con éxito:', result.data);
} else {
console.error('Error al actualizar:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}
// 4. Eliminar usuario
async function deleteUser(userId) {
try {
const response = await fetch(`/api/users/${userId}`, {
method: 'DELETE'
});
const result = await response.json();
if (result.success) {
console.log('Usuario eliminado con éxito');
} else {
console.error('Error al eliminar:', result.error.message);
}
} catch (error) {
console.error('Error de red:', error);
}
}