Создаём RESTful API с помощью Dart за несколько минут

Примечание переводчика: хотелось бы предоставить читателям еще один повод взглянуть на замечательный язык программирования Dart, на этот раз речь пойдёт о том как быстро и легко создавать RESTful API. Для тех, кто не в курсе, здесь понятно описано что это такое.
А тем, кто в курсе, добро пожаловать под кат.

С чего начать

В pub есть отличная библиотека, называется RPC. Это легковесный пакет для создания серверного RESTful API на Dart. И это всё, что нам понадобится.

Давайте начнём с добавления зависимости к нашему проекту в pubspec.yaml:

dependencies:
  rpc: "^0.5.5"

Потом вызовем pub get чтобы загрузить пакеты в наш проект.
Теперь можно импортировать.

import 'package:rpc/rpc.dart';

Создаём класс API

Нам нужно создать класс API который будет содержать в себе наш API. Это Dart класс со специальной аннотацией @ApiClass из библиотеки RPC. Аннотация имеет один обязательный параметр — version, означающий версию предоставляемого API. Например v1. Вы так же можете добавить другие параметры, например, имя, чтобы иметь возможность переименовать API.

@ApiClass(version: 'v1')
class MyApi {
  // Здесь будет содержимое класса
}

Методы API

Мы хотим предоставить возможность делать GET, POST, DELETE и т.д. запросы. Их все мы поместим класс API со специальной аннотацией. Методы могут быть помещены напрямую в API класс или можно использовать API ресурсы.

Методы в классе

Здесь мы создаём методы GET для animals и POST для animal. Каждый метод должен иметь аннотацию @ApiMethod с обязательным параметром path, который указывает путь для вызова нашего метода. Так же можно указать параметр, который укажет тип метода(GET,POST и т.д.). Если этот параметр не указать, то по умолчанию устанавливается GET.

@ApiClass(version: 'v1')
class MyApi {
  List _animals = [];
 
  @ApiMethod(path: 'animals')
  List<Animal> getAnimals() => _animals;
 
  @ApiMethod(path: 'animals', method: 'POST')
  Animal postAnimal(Animal animal) {
    _animals.add(animal);
    return animal;
  }
}

Здесь мы используем List для хранения animals. И предоставляем два метода: getAnimals(), который возвращает список всех животных и postAnimal, который добавляет новую запись animal в список animals. Естественно мы можем расширить данный пример другими методами API.

Чтобы это всё работало, нам понадобится класс Animal:

class Animal {
  int id;
  String name;
  int numberOfLegs;
}

Ресурсы API

Обычно мы хотим разделить наш API на ресурсы, которые предоставляют конкретные API методы. Например, мы хотим иметь один ресурс для API для Animals и один для Person. С помощью библиотеки RPC мы можем сделать это легко.

Создаём класс ресурса и перемещаем туда все связанные с ресурсом методы:

class AnimalResource {
  List _animals = [];
 
  @ApiMethod(path: 'animals')
  List<Animal> getAnimals() => _animals;
 
  @ApiMethod(path: 'animals', method: 'POST')
  Animal postAnimal(Animal animal) {
    _animals.add(animal);
    return animal;
  }
}

Затем создаём экземпляр AnimalResource в нашем классе API, над которым есть аннотация @ApiResource:

@ApiClass(version: 'v1')
class MyApi {
  @ApiResource()
  AnimalResource resource = new AnimalResource();
}

Тестируем API

Чтобы использовать или протестировать наше API, нам надо создать скрипт сервера в папке bin. Нам надо создать здесь ApiServer, добавить туда наш API и создать HttpServer который будет слушать localhost:8080.

library my_server;
 
import 'dart:io';
import 'package:logging/logging.dart';
import 'package:rpc/rpc.dart';
import '../lib/server/api.dart';
 
final ApiServer apiServer = new ApiServer(prettyPrint: true);
 
main() async {
  Logger.root..level = Level.INFO..onRecord.listen(print);
 
  apiServer.addApi(new MyApi());
  HttpServer server = await HttpServer.bind(InternetAddress.ANY_IP_V4, 8080);
  server.listen(apiServer.httpRequestHandler);
  print('Server listening on http://${server.address.host}: ${server.port}');
}

Теперь запускаем Dart скрипт в bin который запускает сервер. Теперь наш API доступен по адресу localhost:8080/myApi/v1. Если мы хотим получить список животных, то создаём GET запрос на localhost:8080/myApi/v1/animals. Или же можем добавить запись сделав POST запрос на тот же адрес localhost:8080/myApi/v1/animals.

Протестировать POST запрос немного сложнее, т.к. для этого надо установить такой инструмент как curl или расширение для хром Postman или Advanced REST client.

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