Как создать REST API?

В этой статье мы познакомимся с API, в частности с RESTful API. Мы рассмотрим их преимущества, ограничения и альтернативы. Кроме того, мы продемонстрируем, как создать REST API с помощью Back4app – одного из лучших BaaS-провайдеров.

Что такое API?

Интерфейс прикладного программирования (API) – это набор правил, определяющих, как два устройства или системы могут взаимодействовать друг с другом. API создаются разработчиками и предназначены для использования другими разработчиками или системами, а не конечными пользователями напрямую. Конечные пользователи обычно используют их косвенно, через так называемые фронтенды или клиенты.

API можно представить как посредника между клиентом и ресурсом или веб-сервисом. Клиент отправляет запрос, затем запрос обрабатывается и, наконец, возвращается ресурс или ответ.

В наши дни API используются практически повсеместно. Большинство компаний имеют множество внутренних и общедоступных API. Только сегодня вы, вероятно, уже взаимодействовали с более чем сотней API. Например, когда вы проверяли время, погоду, прокручивали страницу Facebook или смотрели видео на YouTube.

В чем разница между API и SDK?

Как уже говорилось выше, API – это набор правил, определяющих, как могут взаимодействовать два устройства или системы. С другой стороны, комплект для разработки программного обеспечения (SDK) – это набор инструментов, библиотек и документации, которые помогают разработчикам создавать программное обеспечение для определенной платформы (например, Windows, Web, Android, iOS).

SDK часто используют различные API за кулисами. Во второй части статьи мы рассмотрим практический пример.

Что такое REST?

Архитектурный подход к программному обеспечению, называемый Representational State Transfer (REST), характеризует структуру интернета. Он не является протоколом или стандартом, что позволяет разработчикам применять различные методы реализации. Рой Филдинг представил REST в 2000 году, и вот уже более десяти лет он служит доминирующим стандартом для создания веб-интерфейсов API.

REST основан на протоколе HTTP и использует различные методы HTTP, такие как GET, POST, PUT и DELETE, для работы с ресурсами. Эти операции часто называют CRUD (Create Retrieve Update Delete). REST поддерживает множество форматов данных, включая JSON, HTML, XLT, Python, JavaScript и так далее. Наиболее часто используемым форматом данных является JSON.

Чтобы API считался RESTful, он должен соответствовать следующим шести ограничениям:

1. Клиентская и серверная архитектура – клиентские и серверные компоненты должны быть разделены.
2. Нестационарность – серверным приложениям не разрешается хранить данные клиента между запросами.
3. Кэшируемость – по возможности ресурсы должны быть кэшируемыми на стороне клиента или сервера.
4. Многоуровневая система – API должны допускать посредников, но это не должно влиять на клиента.
5. Единый интерфейс – интерфейс между сервером и клиентом должен быть единым.
6. Код по требованию (необязательно) — позволяет серверу отправлять исполняемый код клиенту.

Разница между REST и RESTful заключается в том, что REST относится к набору ограничений, а RESTful – к API, который соответствует этим ограничениям.

Как работают RESTful API?

RESTful API работают так же, как и браузеры. Основное отличие заключается в том, что браузеры используют HTTP для запроса веб-страниц и других ресурсов с серверов, в то время как RESTful API используют HTTP для запроса и манипулирования ресурсами данных.

Типичный вызов RESTful API выполняется следующим образом:

1. Клиент отправляет запрос на сервер.
2. Сервер аутентифицирует клиента и проверяет, достаточно ли у него прав для выполнения запроса.
3. Сервер обрабатывает запрос, например, выполняет вычисления и извлекает данные из базы данных.
4. Сервер возвращает ответ клиенту.
5. Клиент обрабатывает ответ.

Шаги могут отличаться в зависимости от реализации API. Инструкции по использованию API содержатся в справочнике API (или документации API).

Структура запроса

Запрос содержит следующее:

Пример запроса выглядит следующим образом:

Структура реагирования

Ответ содержит следующее:

Пример ответа выглядит следующим образом:

В чем преимущества RESTful API?

Масштабируемость

RESTful API обладают высокой масштабируемостью и могут масштабироваться как по вертикали, так и по горизонтали. Добавление новых конечных точек или ресурсов оказывает минимальное влияние на производительность API, что позволяет легко масштабировать его по мере необходимости.

Многочисленные форматы данных

RESTful API могут возвращать данные в различных форматах в зависимости от заголовков запроса клиента. Это делает их чрезвычайно гибкими и легко интегрируемыми в существующие системы. Данные могут быть возвращены в виде JSON, XLT, Python, HTML, JavaScript и так далее.

Эффективность

RESTful API отличаются легкостью и меньшими накладными расходами, чем SOAP (Simple Object Access Protocol). Это делает их быстрыми и эффективными в обработке запросов. Типичный RESTful API может обрабатывать от 10.000 до 15.000 запросов в секунду.

Независимость платформы

Еще одно большое преимущество RESTful API заключается в том, что сервер и клиент полностью независимы. Это позволяет разработчикам реализовывать RESTful API и клиентов на нескольких языках программирования, таких как Java, JavaScript, Python и других!

Легко понять

Поскольку REST основан на HTTP, его очень легко понять. Большинство разработчиков почти наверняка хотя бы раз работали с RESTful API или реализовывали его.

Каковы ограничения RESTful API?

Недовыборка и перевыборка данных

Одна из самых больших проблем RESTful API – недостаточная и избыточная выборка данных. Перевыборка происходит, когда возвращается больше данных, чем требуется, а недовыборка – когда возвращается недостаточно данных (в основном это происходит при работе с отношениями).

Отсутствие подписки на данные в режиме реального времени

RESTful API не позволяют подписываться на изменения данных. Это означает, что клиенты должны опрашивать сервер, чтобы обнаружить их. Опрос крайне неэффективен и может привести к ненужному сетевому трафику, увеличению задержек, повышению пропускной способности и снижению масштабируемости.

Отсутствие системы версионирования

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

Для решения вышеупомянутых проблем появилось несколько альтернатив REST. К наиболее популярным из них относятся Simple Object Access Protocol (SOAP), GraphQL и gRPC.

Что такое методы аутентификации RESTful?

RESTful API могут использовать различные методы аутентификации для защиты своих конечных точек. Наиболее часто используемыми методами аутентификации являются:

• HTTP-аутентификация
• Ключи API
• OAuth 2.0
• OpenID Connect
• Аутентификация JWT

Большинство из этих методов требуют от клиента передать свои учетные данные или ключ API в заголовке запроса. При запуске проекта следует учитывать различные методы аутентификации.

Как создать RESTful API?

В этой части статьи мы рассмотрим создание RESTful API с помощью Back4app и установление соединения с фронтендом Next.js.

Пререквизиты

• Опыт работы с JavaScript ES6
• Опыт работы с React и Next.js
• Базовое понимание REST

Что такое Back4app?

Back4app – это удивительное решение BaaS – Backend as a Service. Оно использует программное обеспечение с открытым исходным кодом и предлагает множество функций, помогающих разработчикам быстрее создавать мобильные и веб-приложения. Это позволяет компаниям сосредоточиться на бизнес-логике, не заботясь об облачной инфраструктуре.

Платформа имеет удобную приборную панель и интерфейс командной строки, а также предлагает наборы для разработки программного обеспечения (SDK), совместимые с такими широко распространенными инструментами, как Node.js, Flutter, React Native, Android, Angular и iOS.

У Back4app простая модель ценообразования, которая может подойти для любого приложения. У них также есть бесплатный тарифный план, не требующий кредитной карты, который является хорошим вариантом для разработки, тестирования и создания прототипов.

Чтобы узнать больше о Back4app, пожалуйста, прочитайте Что такое Back4app?

Введение в проект

В этой статье мы создадим простое веб-приложение для блога. Веб-приложение позволит редакторам добавлять статьи, а пользователям – читать их. Приложение будет состоять из двух частей: бэкенда (на основе REST) и фронтенда. Для бэкенда мы будем использовать Back4app, а для фронтенда – React с Next.js.

Бэкэнд

Создать приложение Back4app

Следующие шаги потребуют от вас наличия учетной записи Back4app. Зайдите в него или создайте учетную запись, если у вас ее еще нет.

Перейдите на приборную панель Back4app и создайте новое приложение, нажав кнопку “Создать новое приложение”.

Выберите “Backend as a Service (BaaS)”, дайте ему пользовательское имя и выберите “NoSQL Database” в качестве базы данных. И наконец, нажмите “Создать”, чтобы начать процесс создания приложения.

Back4app потратит несколько минут на подготовку всего необходимого для вашего приложения, такого как база данных, масштабирование и безопасность. Когда ваше приложение будет готово, вы будете перенаправлены на страницу “База данных”.

Определение классов базы данных

Перейдем к определению классов баз данных.

У нас будет два следующих класса:

1. ArticleCategory представляет категорию статьи (например, блокчейн, ИИ, программирование).
2. Статья представляет статью. Статья может иметь несколько категорий (M:N).

Чтобы создать класс, перейдите на приборную панель Back4app и выберите “База данных” на боковой панели. Затем нажмите на “Создать класс”, назовите его ArticleCategoy и включите “Публичное чтение и запись”.

При переходе на производство следует отключить “Публичное чтение и запись” и усилить безопасность с помощью ACL и CLP. Для получения дополнительной информации ознакомьтесь с разделом Безопасность сервера Parse.

Затем добавьте в него следующие поля:

+-----------------------------+-----------------+--------------------+-------------+
| Data type                   | Name            | Default value      | Required    |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | name            | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | slug            | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | description     | <leave blank>      | no          |
+-----------------------------+-----------------+--------------------+-------------+

Выполните те же действия для второго класса под названием Article. Добавьте следующие поля:

+-----------------------------+-----------------+--------------------+-------------+
| Data type                   | Name            | Default value      | Required    |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | title           | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | slug            | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | shortContent    | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| String                      | content         | <leave blank>      | yes         |
+-----------------------------+-----------------+--------------------+-------------+
| Relation -> ArticleCategory | categories      | <leave blank>      | no          |
+-----------------------------+-----------------+--------------------+-------------+

Отлично, вот и все.

Наполнить базу данных

В будущем, когда мы будем тестировать API, нам понадобятся данные для работы. Наполните базу данных примерами категорий и статей.

Чтобы добавить новую статью-категорию, выберите ее на боковой панели и нажмите “Добавить строку”.

Вы можете использовать эти категории статей или придумать свои:

+------------+------------+---------------------------------------------------------+
| name       | slug       | description                                             |
+------------+------------+---------------------------------------------------------+
| Blockchain | blockchain | Blockchain, crypto & more!                              |
+------------+------------+---------------------------------------------------------+
| AI         | ai         | Artificial intelligence, LLMs, stable diffusion.        |
+------------+------------+---------------------------------------------------------+

Вы также можете использовать ChatGPT для создания образцов данных. Чтобы узнать больше о ChatGPT, прочитайте статью Как использовать ChatGPT для создания приложения?

Сделайте то же самое для класса Article:

+------------------+---------------+--------------+---------+-----------------------+
| title            | slug          | shortContent | content | categories            |
+------------------+---------------+--------------+---------+-----------------------+
| Beyond Crypto    | beyond-crypto | ...          | ...     | <blockchain.objectId> |
+------------------+---------------+--------------+---------+-----------------------+
| The Rise of AI   | rise-of-ai    | ...          | ...     | <ai.objectId>         |
+------------------+---------------+--------------+---------+-----------------------+
| What is ChatGPT? | chatgpt       | ...          | ...     | <ai.objectId>         |
+------------------+---------------+--------------+---------+-----------------------+

Обязательно замените и на фактический идентификатор объекта ArticleCategory. В моем случае это SxS0yiWDij и Hf8yBDTO79 (изображение выше для справки).

REST API

Самое замечательное в Back4app то, что по мере определения классов базы данных Back4app автоматически создаст для вас REST API. Созданный REST API позволит вам выполнять основные CRUD-операции со всеми классами в вашей базе данных.

Консоль REST API

Чтобы протестировать API, перейдите на приборную панель Back4app и выберите “API > Консоль > REST” на боковой панели. Затем выберите GET в качестве типа запроса и classes/Article в качестве конечной точки. И наконец, нажмите “Отправить запрос” в правой нижней части экрана, чтобы отправить запрос.

Этот запрос вернет все статьи в вашей базе данных. Вы должны получить аналогичный ответ:

{
   "results":[
      {
         "objectId": "yEaR8K44il",
         "title": "Beyond Crypto",
         "slug": "beyond-crypto",
         "shortContent": "...",
         "content": "...",
         "createdAt": "2023-04-17T14:26:19.016Z",
         "updatedAt": "2023-04-17T14:26:30.922Z",
         "categories": {
            "__type": "Relation",
            "className": "ArticleCategory"
         }
      },
      {
         "objectId": "l46nMkHElH",
         "title": "What is ChatGPT?",
         "slug": "chatgpt",
         "shortContent": "...",
         "content": "...",
         "createdAt": "2023-04-17T14:27:34.931Z",
         "updatedAt": "2023-04-17T14:27:42.636Z",
         "categories": {
            "__type": "Relation",
            "className": "ArticleCategory"
         }
      }
      // ...
   ]
}

Консоль REST также позволяет выполнять операции POST, PUT и DELETE. Кроме того, вы можете использовать параметры Parse Query для фильтрации данных, обработки отношений и многого другого.

Например, если вы хотите получить статьи, относящиеся к категории “Блокчейн”, вы можете использовать следующий оператор where:

where={"categories": {
    "__type": "Pointer", "className": "ArticleCategory", "objectId": "<objectId>"
}}

Обязательно замените на objectId блокчейна.

Подробнее о параметрах запроса можно узнать из руководства по Parse REST API.

cURL

Консоль REST – это здорово, но когда вы работаете над реальными приложениями, вам понадобится более программистский подход к API-запросам. Одним из инструментов, которые вы можете использовать, является cURL – инструмент командной строки для различных протоколов, таких как HTTP, FTP и SMTP.

Пример команды cURL для получения списка категорий статей выглядит следующим образом:

$ curl -X GET \
  -H "X-Parse-Application-Id: YOUR_APPLICATION_ID" \
  -H "X-Parse-REST-API-Key: YOUR_REST_API_KEY" \
  https://parseapi.back4app.com/classes/ArticleCategory | jq

Вы можете получить ключи в разделе “Back4app Dashboard > App Settings > Security & Keys”.

Как видите, при использовании cURL необходимо указать тип метода HTTP, а также предоставить идентификатор приложения и ключ REST API. Кроме того, вы можете передать ответ в jq, чтобы автоматически отформатировать его и выделить цветом.

Справочник по API

Еще одна замечательная особенность Back4app заключается в том, что он автоматически генерирует ссылки на API для всех классов вашей базы данных. Каждый раз, когда вы вносите изменения, они отражаются в документации.

Чтобы получить доступ к справочнику API, выберите “База данных” на боковой панели и используйте три точки в правом верхнем углу экрана, чтобы увидеть все опции. И наконец, выберите “Справочник API”.

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

Это все, что касается бэкенда. В следующем разделе мы рассмотрим, как реализовать фронтенд, который может взаимодействовать с бэкендом.

Frontend

Как уже говорилось выше, для создания фронтенда мы будем использовать React с Next.js 13. Вообще говоря, существует три способа подключения к бэкенду на основе Parse с фронтенда на JavaScript:

1. С помощью REST API (HTTP-запросы и ответы)
2. С помощью GraphQL API (о нем рассказывается в этой статье)
3. С помощью JavaScript SDK

Вам следует выбрать последний или второй вариант. Прямое использование REST API не рекомендуется в клиентских приложениях, которые могут использовать Parse SDK (например, JavaScript, Flutter, Android, iOS, Xamarin). Это связано с тем, что Parse SDK позволяет писать более чистый код и менее подвержен ошибкам. За кулисами Parse SDK используют REST API.

Создать следующее приложение

Приступайте к загрузке проекта Next.js с помощью утилиты create-next-app. Откройте терминал и выполните следующую команду:

$ yarn create next-app

√ What is your project named? ... back4app-graphql
√ Would you like to use TypeScript with this project? ... No
√ Would you like to use ESLint with this project? ... Yes
√ Would you like to use the `src/` directory with this project? ... No
√ Would you like to use the experimental `app/` directory with this project? ... No
√ What import alias would you like configured? ... @/*

Successfully created a Next.js app.

Затем запустите сервер разработки:

$ yarn dev

Перейдите по адресу http://localhost:3000, и вы увидите целевую страницу Next.js.

ChakraUI

Чтобы упростить процесс создания UI/UX, мы будем использовать ChakraUI. Chakra UI – это несложная, модульная и удобная библиотека компонентов, которая предоставляет все необходимые элементы для разработки React-приложений.

Если у вас возникнут проблемы, обратитесь к разделу ChakraUI: Начало работы с Next.js.

Сначала установите Chakra и все необходимые компоненты, запустив их:

yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion

Далее перейдите к файлу _pages/app.tsx и оберните свое приложение с помощью ChakraProvider следующим образом:

// pages/_app.tsx

import "../styles/globals.css";
import {ChakraProvider, extendTheme} from "@chakra-ui/react";

export const theme = extendTheme({});

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme}>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

export default MyApp;

Не забудьте импортировать ChakraProvider:

import {ChakraProvider} from "@chakra-ui/provider";

Загрузите скрипт цветового режима перед контентом, чтобы избежать случайных цветовых вспышек. Для этого вы можете использовать _document.js следующим образом:

// pages/_document.js

import {ColorModeScript} from "@chakra-ui/react";
import { Html, Head, Main, NextScript } from "next/document";
import {theme} from "@/pages/_app";

export default function Document() {
  return (
    <Html lang='en'>
      <Head />
      <body>
        <ColorModeScript initialColorMode={theme.config.initialColorMode} />
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Отлично, вы успешно установили ChakraUI.

Пользовательский интерфейс

Перейдем к реализации пользовательского интерфейса. Мы создадим следующие две страницы:

1. / отображает список статей
2. / / отображает конкретную статью

Начните с индекса. Замените содержимое pages/index.js на следующее:

// pages/index.js

import {Card, CardBody, Container, Heading, 
        Link, Spinner, Stack, Text} from "@chakra-ui/react";
import NextLink from "next/link";
import {useEffect, useState} from "react";

export default function Home() {

  const [isLoading, setIsLoading] = useState(true);
  const [articles, setArticles] = useState([]);

  return (
    <>
      <main>
        <Container maxW="container.lg">
          <Heading as="h1" my="4">
            back4app-rest
          </Heading>
          {isLoading ? (
            <Spinner size="lg"/>
          ) : (
            <Stack spacing="4" direction="column">
              {articles.map((article, index) => (
                <Card key={index} w="100%">
                  <CardBody>
                    <Stack spacing="3">
                      <Heading size="md">
                        <Link as={NextLink} href={article.get("slug")}>
                          {article.get("title")}
                        </Link>
                      </Heading>
                      <Text>
                        {article.get("shortContent")}
                      </Text>
                    </Stack>
                  </CardBody>
                </Card>
              ))}
            </Stack>
          )}
        </Container>
      </main>
    </>
  );
}

1. Мы подготовили состояния articles и isLoading, которые мы будем использовать позже при получении данных.
2. Для разработки пользовательского интерфейса мы использовали базовые компоненты ChakraUI.
3. Чтобы отобразить все статьи, мы перебираем состояние articles.

Далее перейдите к файлу pages/[slug].js и измените его на следующий:

// pages/[slug].js

import {useRouter} from "next/router";
import {Card, CardBody, Container, Heading,
        Link, Spinner, Stack, Text} from "@chakra-ui/react";
import NextLink from "next/link";
import {useEffect, useState} from "react";

export default function Article() {

  const router = useRouter();
  const {slug} = router.query;

  const [isLoading, setIsLoading] = useState(true);
  const [article, setArticle] = useState(null);

  return (
    <>
      <main>
        <Container maxW="container.lg">
          <Heading as="h1" my="4">
            back4app-rest
          </Heading>
          {isLoading ? (
            <Spinner size="lg"/>
          ) : (
            <>
              {article == null ? (
                <Text>This article does not exist.</Text>
              ) : (
                <Card w="100%">
                  <CardBody>
                    <Stack spacing="3">
                      <Heading size="md">{article.get("title")}</Heading>
                      <Text>
                        {article.get("content")}
                      </Text>
                      <Text fontSize="sm">
                        Posted on {new Date(article.get("createdAt")).toDateString()}
                      </Text>
                    </Stack>
                  </CardBody>
                </Card>
              )}
            </>
          )}
          <Text size="sm" mt="2" align="right">
              <Link as={NextLink} href="/">← Go back</Link>
          </Text>
        </Container>
      </main>
    </>
  );
}

1. Мы подготовили штат для хранения статьи.
2. Мы использовали Next Router для получения параметра slug из URL.

Интеграция с бэкэндом

В этом последнем разделе мы соединим фронтенд с бэкендом.

Чтобы использовать Parse SDK, нам сначала нужно установить его. Выполните следующую команду:

$ yarn add parse @react-native-async-storage/async-storage

Далее перейдите в файл pages/_app.js и инициализируйте Parse следующим образом:

// pages/_app.js

const PARSE_HOST_URL = "https://parseapi.back4app.com/";
Parse.initialize("YOUR_APPLICATION_ID", "YOUR_JAVASCRIPT_KEY");  // replace me
Parse.serverURL = PARSE_HOST_URL;

export default function App({ Component, pageProps }) {
  return (
      // ...
  );
}

Не забывайте об импорте:

import Parse from "parse/dist/parse.min.js";

Для получения статей на индексной странице мы можем использовать Parse.Query. После получения данных мы можем сохранить их в articles и установить значение isLoading в false:

// pages/index.js

export default function Home() {

  // ...

  const getArticles = async () => {
    const query = new Parse.Query("Article");
    setArticles(await query.find());
    setIsLoading(false);
  };

  useEffect(() => {
    getArticles();
  }, []);

  return (
    // ...
  );
}

Затем мы можем сделать то же самое для статьи в pages/[slug].js:

// pages/[slug].js

export default function Article() {

  // ...

  const getArticle = async () => {
    const query = new Parse.Query("Article");
    query.equalTo("slug", slug);
    const results = await query.find();
    setIsLoading(false);
    if (results.length === 0) return;
    setArticle(results[0]);
  };

  useEffect(() => {
    getArticle();
  }, []);

  return (
    // ...
  );
}

Опять же, не забудьте импортировать Parse в оба файла.

import Parse from "parse/dist/parse.min.js";

Запустите сервер разработки Next (если он еще не запущен) и зайдите на сайт http://localhost:3000 в своем любимом веб-браузере. Вы должны увидеть список ваших статей, а сами статьи должны быть доступны для чтения.

Заключение

В этой статье вы узнали об API, RESTful API, их преимуществах и недостатках. Теперь вы должны уметь создавать свои простые RESTful API и подключаться к ним из внешнего приложения.

Вы можете получить окончательный исходный код на GitHub.

Если вам понравилась эта статья, ознакомьтесь также со статьей Как сделать GraphQL API.