itmo_conspects

Лекция 4. Разработка API

API (Application Programming Interface) - программный интерфейс приложения

Здесь интерфейс - это способы взаимодействия с этим приложением, то есть то, что нужно делать, чтобы обменяться данными с приложением или совершить какое-либо действие

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

Вследствие этого появились 2 подхода к разработке приложения:

Сначала код (Code first) - сначала создается бизнес-логика, а потом к ней добавляется контракт
Сначала контракт (Contract first) - сначала описываются способы взаимодействия, а затем пишется код

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

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

Всего выделилось несколько форматов веб-интерфейсов:

SOAP API (Simple Object Access Protocol, дословно “Протокол доступа к простым объектами”) - протокол, по которому веб-сервисы используют XML-документы для обмена запросами и ответами
RPC (Remote Procedure Call, Удаленный вызов процедуры) - способ вызвать функцию на удаленном компьютере так, будто она вызывается локально

Сам вызов передается в формате XML (тогда интерфейс называется XML-RPC), JSON (тогда JSON-RPC) или другом удобном

Среди реализаций RPC выделяют фреймворк gRPC, созданный Google. В нем данные передаются в формате буферов протокола (Protocol Buffer, или сокращенно protobuf) через протокол HTTP/2, что позволяет сделать передаваемые данные компактнее
REST API (REpresentational State Transfer) - стиль, по которому веб-сервисы позволяют отправлять запросы к ресурсам по URL. Нужная операция указывается как HTTP-метод (GET, POST и так далее), а путь (так называемая конечная точка или эндпоинт) указывает тип ресурса

В качестве формата данных используется JSON или XML
GraphQL API (от Graph Query Language) - технология, разработанная в Facebook, которая позволяет пользователям получать именно те данные, которые им нужны (например, статьи, созданные пользователями с 1000 или более подписчиками) через один запрос

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

Сейчас большинство веб-интерфейсов представлено в архитектурном стиле REST (так называемые RESTful API), который был описан Роем Филдингом в 2000 году

Ключевая идея REST в том, что у всех доступных ресурсов (таких как пользователи, статьи, продукты и так далее) есть свой URL, и над каждым таким ресурсом действие делается через HTTP-метод по соответствующему URL

Например, GET-запрос по URL http://example.com/users?limit=100 вернет первых 100 пользователей приложения. Здесь:

http://example.com - домен
http://example.com/users - URL ресурса
?limit=100 - параметры запроса

В качестве формата передачи данных для REST чаще всего используют JSON (так как он удобен для обработки JavaScript-кодом), но ничего не мешает использовать другие форматы

Также Рой Филдинг описал 5 требований к архитектуре REST API:

Модель “Клиент-Сервер” - отделение потребности интерфейса клиента от потребностей сервера, хранящего данные, повышает переносимость кода клиентского интерфейса на другие платформы, а упрощение серверной части улучшает масштабируемость.
Отсутствие состояния (сессии клиента) - между запросами сервер не должен хранить состояние клиента, то есть запрос сам по себе должен содержать всю необходимую информацию
Кэширование - должно быть явное обозначение кэшируемых и некэшируемых ответов, чтобы клиент получал актуальную информацию
Унифицированный интерфейс - все ресурсы идентифицируются в запросах; каждое сообщение содержит достаточно информации, чтобы понять, каким образом его обрабатывать; если клиент хранит представление ресурса, включая метаданные, то он обладает достаточной информацией для модификации или удаления ресурса
Прозрачность слоев - клиент не способен определить, общается он напрямую с сервером или с промежуточным слоем

Для упрощения документирования REST-интерфейсов разработали спецификации OpenAPI и RAML. Благодаря им, можно описать, что делает каждый метод, какие параметры ему нужны и так далее, а затем сгенерировать готовый документ

Рассмотрим OpenAPI - спецификация позволяет описать API на языке YAML или JSON:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            maximum: 100
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pets'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    # ...
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      maxItems: 100
      items:
        $ref: '#/components/schemas/Pet'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

Здесь описаны:

URL запросов
Описание запроса
Тип данных параметров и моделей
Возможные ответы (в том числе содержащие ошибку)

Затем такие инструменты, как Swagger, могут сгенерировать HTML-страницу с документацией:

Petstore

This site is open source. Improve this page.