dorm_http_database 2.0.0-dev.5

An HTTP and JSON database engine for dORM applications that access remote APIs through typed repositories and queries.

dorm_http_database

dorm_http_database maps dORM repositories to a configured REST-shaped HTTP/JSON API. It uses an application-owned http.Client and does not assume one universal REST convention.

Backend and runtime

The backend is an HTTP server that implements the mapping supplied by the application. The package can run wherever package:http is supported.

Install

dart pub add dorm_framework
dart pub add dorm_http_database
dart pub add http
dart pub add dorm_annotations
dart pub add --dev dorm_generator
dart pub add --dev build_runner

Create the engine and Dorm facade

The mapping is part of the engine configuration, so the generated Dorm facade can remain independent of one particular REST convention.

Configure the mapping

The mapping declares how each entity becomes an HTTP resource:

import 'package:http/http.dart' as http;
import 'package:dorm_http_database/dorm_http_database.dart';

final mapping = HttpMapping.byTableName({
  'users': HttpResourceMapping(path: 'users'),
});

final engine = Engine(
  client: http.Client(),
  baseUri: Uri.parse('https://api.example.test/'),
  mapping: mapping,
  headers: const {'Authorization': 'Bearer [PLACEHOLDER: token]'},
);

final dorm = Dorm(engine);

The application owns and closes the http.Client. Configure batch endpoints, identity placement, response envelopes, and query parameter conventions through HttpResourceMapping and HttpMapping.

Use repositories

final User user = await dorm.users.repository.put(
  Creation.auto(
    dependency: const UserDependency(),
    data: UserData(name: 'Ada'),
  ),
);

final List<User> users = await dorm.users.repository.peekAll(
  Filter.text('Ada', field: UserEntity.fields.name),
);

The default codec maps dORM fields to REST query parameters. HttpJsonCodec can read an object, a list, or a configured data envelope.

Identities, filters, pages, and relationships

The mapping controls resource paths, query parameters, ordering, limits, offsets, and response envelopes. Relationships use readable-operation fallbacks and may make several requests.

Backend-generated identities

When the remote API creates the identity, declare DatabaseGeneratedIdSpec and configure the resource with HttpIdentityLocation.none. The creation response must be a scalar identity or a complete JSON representation. Use HttpCreationCodec for an envelope such as a response containing id.

Transactions

The HTTP engine does not implement the portable TransactionalDorm capability.

Streams

Relationships use readable-operation fallbacks and can make several HTTP requests. pull and pullAll emit the initial read only; they do not poll or use SSE/WebSocket connections.

Batch operations require configured batch endpoints. The engine never simulates a batch by sending independent requests and presenting them as atomic.

Non-success responses produce HttpDatabaseException with status, method, URI, and available response body. Transport errors from http.Client are propagated.

Schema, errors, and limitations

The server must implement the endpoint contract configured by the application. Authentication, retries, caching, observability, and authorization remain client or server concerns. The package does not provide HTTP transactions, schema migrations, arbitrary selectors, or a universal API convention.

Run the example

See the package example for the local HTTP contract, environment configuration, generation, and Dart commands.

Links

• Run with HTTP/JSON
• http
• dorm_framework
• GitHub repository