AI SaaS Builder · Урок

Проектирование RESTful API

Создавайте хорошо структурированные и эффективные API для бесперебойного обмена данными между клиентской и серверной частями.

«Проектирование RESTful API» — бесплатный урок AI SaaS Builder на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI SaaS Builder, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI SaaS Builder содержит 4 уроков всего.

API: канал связи Вашего приложения

В современном программном обеспечении разным частям приложения часто требуется обмениваться данными. Особенно это важно для AI SaaS, где внешняя часть приложения, которую видят пользователи, должна взаимодействовать с мощной внутренней частью, отвечающей за работу ИИ.

API (программный интерфейс приложения) можно сравнить с меню в ресторане. В нём перечислены блюда (функции), которые можно заказать, указано, какие ингредиенты (параметры) нужно предоставить и что Вы получите в ответ (результаты).

Для веб-приложений RESTful API — самый распространённый способ обмена данными между внешней и внутренней частями системы через интернет.

Что такое REST

REST — это сокращение от Representational State Transfer («передача представительного состояния»). Это архитектурный стиль, а не протокол, который определяет набор ограничений для проектирования веб-служб.

Представьте REST как чертёж, показывающий, как внутренняя часть приложения должна предоставлять свои службы другим приложениям. Соблюдение принципов REST делает API:

масштабируемым: способным обрабатывать больше запросов;
гибким: легко развиваемым и адаптируемым;
удобным в сопровождении: более простым для понимания и исправления.

Основная идея заключается в том, чтобы рассматривать всё как «ресурс».

Основные принципы REST

REST опирается на несколько ключевых принципов, которые обеспечивают его преимущества:

Клиент и сервер: разделение ответственности. Клиент отвечает за пользовательский интерфейс, а сервер — за хранение и обработку данных.
Отсутствие состояния: каждый запрос клиента к серверу должен содержать всю информацию, необходимую для его понимания. Сервер не хранит сведения о состоянии клиента между запросами.
Возможность кэширования: ответы можно помечать как доступные для кэширования, чтобы повысить производительность.
Единый интерфейс: это важнейший принцип проектирования. Он упрощает систему благодаря единообразному способу взаимодействия с ресурсами.

Ресурсы: существительные Вашего API

Принцип «единого интерфейса» означает, что API должен сосредоточиться на ресурсах. Ресурс — это любая информация, которой можно дать имя, например пользователь, товар или заказ.

При проектировании рассматривайте ресурсы как существительные, а не как глаголы. Конечные точки API (URL) должны отражать эти существительные, обычно во множественном числе.

Вместо /getUser используйте /users
Вместо /createProduct используйте /products
Вместо /deleteOrder/123 используйте /orders/123

Такой подход делает API понятным и единообразным.

Методы HTTP: действия

После того как Вы определили ресурсы (например, /products), используйте стандартные методы HTTP, чтобы выполнять над ними действия. Эти методы подобны глаголам для Ваших существительных.

GET: получение данных (например, GET /products — получить все товары);
POST: создание новых данных (например, POST /products — добавить новый товар);
PUT: обновление или замена существующих данных (например, PUT /products/123 — обновить товар 123);
DELETE: удаление данных (например, DELETE /products/123 — удалить товар 123).

Существует также PATCH для частичных обновлений, но эти четыре метода являются основными.

Пример: получение данных (GET)

Рассмотрим, как клиент взаимодействует с RESTful API для получения данных с помощью метода GET.

В данном случае мы получаем конкретную публикацию из общедоступного тестового API. URL /posts/1 однозначно указывает на нужный ресурс.

import requests

# Define the API endpoint for a specific post
url = "https://jsonplaceholder.typicode.com/posts/1"

# Send a GET request
response = requests.get(url)

# Check if the request was successful (status code 200)
if response.status_code == 200:
  print("Successfully retrieved data:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

Пример: создание данных (POST)

Чтобы создать новый ресурс, используйте метод POST. Новые данные передаются в теле запроса, обычно в формате JSON.

Обратите внимание: запрос отправляется к конечной точке ресурса во множественном числе (/posts) без ID, поскольку идентификатор назначит сервер.

import requests
import json

# Define the API endpoint for creating posts
url = "https://jsonplaceholder.typicode.com/posts"

# Define the data for the new post
new_post_data = {
  "title": "CoddyKit Lesson",
  "body": "This is a new post from CoddyKit!",
  "userId": 1
}

# Send a POST request with the JSON data
response = requests.post(url, json=new_post_data)

# Check if the request was successful (status code 201 Created)
if response.status_code == 201:
  print("Successfully created post:")
  print(response.json())
else:
  print(f"Error: {response.status_code} - {response.text}")

Коды состояния HTTP: ответ API

После выполнения запроса API отправляет код состояния HTTP. Это трёхзначное число сообщает клиенту, успешно ли выполнен запрос, произошла ли ошибка и какого она типа.

Успешное выполнение, 2xx: 200 OK (общий успешный ответ), 201 Created (ресурс создан), 204 No Content (успешный ответ без данных для возврата).
Ошибка клиента, 4xx: 400 Bad Request (неправильно сформированный запрос), 401 Unauthorized (отсутствуют данные аутентификации), 403 Forbidden (аутентификация пройдена, но доступ запрещён), 404 Not Found (ресурс не существует).
Ошибка сервера, 5xx: 500 Internal Server Error (на сервере что-то пошло не так).

Использование подходящих кодов состояния крайне важно для хорошо спроектированного API.

Формат данных: JSON для простоты

При отправке данных в RESTful API и получении данных из него часто используется формат JSON (JavaScript Object Notation).

JSON отличается компактностью, понятен человеку и легко обрабатывается большинством языков программирования. Он представляет данные в виде пар «ключ — значение» и массивов, что делает его идеальным для структурированной информации.

Хотя XML когда-то был популярен, JSON стал фактическим стандартом для веб-API благодаря простоте и эффективности.

Версионирование Вашего API

По мере развития AI SaaS будет развиваться и Ваш API. Вы можете добавлять новые возможности, изменять структуры данных или даже удалять старые конечные точки. Именно здесь пригодится версионирование API.

Версионирование позволяет вносить изменения, не нарушая работу существующих приложений, которые используют Ваш API. Распространённый подход — указывать номер версии в URL:

/v1/users (версия 1)
/v2/users (версия 2)

Это обеспечивает обратную совместимость и более плавный переход для пользователей.

Проверьте навыки проектирования API

Какие из перечисленных принципов являются основными принципами проектирования RESTful API?

Повторение: проектирование надёжных API

Поздравляем! Вы изучили основы проектирования RESTful API.

API обеспечивают обмен данными между внешней и внутренней частями приложения.
REST — это архитектурный стиль, основанный на ресурсах и стандартных методах HTTP.
Ресурсы следует обозначать существительными во множественном числе в URL.
Методы HTTP (GET, POST, PUT, DELETE) определяют действия над этими ресурсами.
Коды состояния HTTP предоставляют важную информацию о результатах запросов.
JSON — предпочтительный формат данных для обмена через API.
Версионирование API обеспечивает плавное развитие и обратную совместимость.

Освоение этих понятий — ключ к созданию масштабируемых и удобных в сопровождении внутренних частей AI SaaS.

Часто задаваемые вопросы

Урок «Проектирование RESTful API» бесплатный?

Да — полный текст урока «Проектирование RESTful API» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI SaaS Builder, подпишись на CoddyKit PRO. Курс AI SaaS Builder содержит 4 уроков всего.

Чему я научусь в уроке «Проектирование RESTful API»?

Создавайте хорошо структурированные и эффективные API для бесперебойного обмена данными между клиентской и серверной частями. Ты практикуешь AI SaaS Builder с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI SaaS Builder?

Предыдущий опыт не требуется. AI SaaS Builder на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Проектирование RESTful API»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI SaaS Builder?

Да. Каждый урок AI SaaS Builder включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к AI SaaS Builder