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

Но как программные приложения взаимодействуют друг с другом? Ведь, они делают это через API – прикладной программный интерфейс. В этой статье вы узнаете, что такое API. Мы будем концентрироваться именно на Web API и их дизайне и разработке.

Что такое Web API?

Web API – это тип API, предназначенный для использования через Web. Другими словами, веб-базированные программные приложения, системы и услуги используют Web API для обмена информацией через Интернет. Они отправляют запросы и получают ответы, обычно в форматах, таких как JSON или XML.

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

  1. Взаимодействие: API являются технологически независимыми, что意味着 они позволяют различным системам программного обеспечения общаться друг с другом независимо от технологической основы. Это позволяет разработчикам интегрировать различные приложения без проблем.

  2. Скалярность: Web API поддерживают модульную разработку, позволяя разрабатывать, дебатировать и масштабировать независимо различные компоненты приложения. Это значительно улучшает масштабность системы.

  3. Флексиbilitty и Разширяемость: Согласно стандартным практикам и четко определенным правилам, Web API помогают расширять функциональность приложений. Они также достаточно гибкие, чтобы разрешать разработчикам создавать динамичные приложения.

Образцы Разработки Web API

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

  • REST – Representational State Transfer (REST) API использует протокол HTTP для выполнения операций. Они работают в stateless-режиме, что означает, что каждая запрос должен включать все необходимые сведения для того, чтобы получатель мог обработать и ответить.

  • SOAP – Simple Object Access Protocol использует XML для структурированного обмена информацией.

  • ГрафолQL

    – используется для запросов и манипуляций API.

  • gRPC – фреймворк для удаленных процедурных вызовов, использующий HTTP/2 для передачи информации.

В upcoming sections мы будем исследовать дизайн и разработку API, сфокусируясь на REST API, как на протоколе, центральном для нашего разговора.

Общение потребностей и целей

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

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

Определение ресурсов и контроллеров

REST API фокусируется на ресурсах, которые являются сущностями, представляющими данные или объекты в системе. Каждый ресурс идентифицируется уникальным URI, называемым идентификатором ресурса. Эти ресурсы могут быть доступны и манипулироваться через контроллеры, которые являются специфическими URL-ами, принимающими и обрабатывающими запросы от клиента.

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

Рассмотрим следующий пример: https://api.example.com/products

Конечный пункт соответствует лучшим практикам использования существительного для ресурса (в этом случае, products). Обратите внимание, что я использовал склонение – products? Также рекомендуется использовать склонение, если вы работаете с коллекцией объектов.

Тем не менее, следующий конечный пункт https://api.example.com/add-product не рекомендуется, поскольку он использует глагол и пытается описать действие над ресурсом. Этот подход может стать сложным для более сложных операций.

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

Например: https://api.example.com/categories/{categoryId}/products/{productId}.
Здесь мы определяем конечную точку, которая поддерживает ясную иерархию между ресурсами category и product.

Использование HTTP методов и статусных кодов

В REST API-ах используется HTTP для связи между клиентом и сервером. HTTP имеет стандартные методы, которые primary used to perform операции с ресурсами. Ниже приведено список этих методов с их целями:

  • GET – Запросить детали ресурса. Эти детали возвращаются сервером в теле сообщения ответ.

  • POST – Создание нового ресурса.Detaily novogo resursa, kotoryy trebuet sozdat’, sdelannye v sobstvennosti zaprositelya.

  • PUT – Создание или обновление ресурса в зависимости от его наличия.Detaily novogo ili ubezhdennego resursa, kotoryy trebuet sozdat’ ili ubezhdat’, sdelannye v sobstvennosti zaprositelya.

  • DELETE – Удаление ресурса.

  • PATCH – частичное обновление ресурса.Peredelki, kotoryy trebuet sozdat’, sdelannye v sobstvennosti zaprositelya.

Rekomendirovannaya metodika dlya razvitiya dobrego ogranichennogo REST API predstavljaetsya ispol’zovaniem etih HTTP metod sravneniy dlya proveryki sravneniy sovpadeniy s ucheta (sozdanie, ctenie, ubezhdenie, ubiistvo) na resursakh. Takoee API trebuet vratit’ uchitelem ustojchivoj koda HTTP v soobshenii soderzhaniya.

Kod statusa reflektira spasibo rezultat zaprositelya. Navsegda est’ nekotorye znanye kody statusov HTTP, soderzhanie kotryh mozhet ispol’zovat’:

  • 200 OK

  • 201 Created

  • 204 No Content

  • 400 Bad Request

  • 401 Неавторизован

  • 403 Запрещён

  • 404 Не найдено

  • 500 Ошибка сервера

  • 503 Servis netvoretsa

  • 504 Timeout portov

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

Стратегии версионирования

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

maintenance различных версий сделает ваши API обратно совместимыми и позволит клиентам использовать нужную им версию API по их потребностям.Fragment из інформативного блогу на сайті Postman объясняет, когда идеально версионировать ваши API:

Вы должны верифицировать вашу API каждый раз, когда вы делаете изменение, которое потребует, чтобы пользователи изменили свои базы кода, чтобы продолжать использовать API. Этот тип изменения называется “breacking change” (разрывающим изменением), и оно может быть сделано для входных и выходных структур данных API, обратной связи о успехе и ошибках и механизмов безопасности.

Верификация API может осуществляться по-различным методам. Вот несколько из них:

  • Верификация URI: Включите номер версии в URL-путь. Например, https://api.example.com/v1/products.

  • Верификация параметра запроса: Укажите номер версии в качестве параметра запроса в URL. Например, https://api.example.com/products?version=1.

  • Верификация заголовка: Включите номер версии в HTTP-заголовки запроса. Например, используя пользовательский заголовок, как X-API-Version: 1.

  • Content Negotiation: Указывайте версию в заголовке Accept запроса, часто используя типы медиа. Например, Accept: application/vnd.example.v1+json.

    .

  • Embedded Versioning: Встраивание номера версии в медиатип ответа. Например, application/vnd.example.product-v1+json.

    .

Security Considerations

Еще один важный аспект, который необходимо учитывать при разработке API, – это безопасность. Вот несколько ключевых моментов, которые следует запомнить:

  1. Введите HTTPS для шифрования информации, которой обмениваются клиент и сервер.

  2. Введите аутентификацию и авторизацию, чтобы гарантировать, что только пользователи с нужными привилегиями могут выполнять операции с ресурсами. К распространенным методам относятся базовая аутентификация, аутентификация с использованием носителя или токена, JWT и OAuth 2.0. Также реализуйте контроль доступа на основе ролей для управления доступом к ресурсам.

  3. Implement input validation and sanitization to prevent vulnerability attacks like SQL injection and Cross-Site Scripting (XSS).

  4. Implement rate limiting and throttling to control the number of requests a client can make to the server within a specific time frame. This helps prevent excessive load on the server.

Documentation

One key but often overlooked aspect of API development is documentation. It is crucial to document your API so users understand its features and functionalities.

The documentation must be comprehensive, easy to understand, and follow standard practices. Include examples of request and response bodies, HTTP status codes used, and more. You can follow the Open API specification for describing your RESTful APIs.

Sorting, Filtering and Pagination Strategies

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

Чтобы решить эту проблему, вы должны включить сортировку и фильтрацию записей. Также вы должны реализовать пагинацию, чтобы разбить количество записей, которые будут извлекаться, и установить лимит для удобства навигации и обработки.

Мониторинг использования, логирование и состояние здоровья

Добавлять логирование запросов и ответов вашего API для помощи в отладке является хорошей идеей. Мониторинг использования API поможет вам понять общее поведение и производительность приложения.Regular health checks can help you take necessary action if there are any issues. All these steps will make the API more robust and reliable.

Заключение

API, особенно Web API, являются необходимым элементом для взаимодействия приложений через интернет.

Эта статья объясняет, что такое Web API, porque они важны и различные стратегии для их разработки, сфокусируясь на REST API. Вы также leanred о ключевых темах, таких как определение ресурсов и конечных точек, использование стандартных HTTP методов и статусных кодов, стратегии версионирования, соображения безопасности, документация и многое другое.

Если вам этот опус интересен, пожалуйста, посмотрите на мои другие статьи на freeCodeCamp и свяжитесь с мной на LinkedIn.