Dart
The Dart SDK publishes to pub.dev and works in Dart servers and CLIs and in Flutter apps on iOS, Android, macOS, Windows and Linux. It needs Dart 3 and has no runtime dependencies.
The transport is dart:io's HttpClient, which browsers do not provide, so the package does not build for Flutter web.
Install
dart pub add your_org_api_clientOr for Flutter:
flutter pub add your_org_api_clientOptions
Set these for Dart in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.
Synchronous companionschoiceinclude adds a …Sync method beside each asynchronous one.
syncMethods
Client stylechoiceclass gives callers a client to create. functions gives free functions to import. See client style.
clientStyleByLang.dart
NamespacechoiceGroups operations by tags, by URL path, or not at all with none.
namespaceByLang.dart
Method namingchoiceshort drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.
methodNaming
Argument stylechoiceobject takes one parameters object, and positional takes arguments in order. See argument style.
outputByLang.dart.argumentStyle
Doc commentschoicefull or minimal.
outputByLang.dart.docComments
Usage examplechoicefull or concise.
outputByLang.dart.usageExample
File headerchoiceinclude or omit. Omitting it needs the Enterprise plan. Set for every language at once.
fileHeader
Package name
pub.dev names are global, lowercase, and use underscores. Hyphens are not allowed:
acme_apiEvery package gets a pub points score covering documentation, static analysis, and platform support, shown on the listing. Doc comments set to full and a real README both feed it. A low score is the first thing a prospective user sees.
pub.dev lets you retract a version within 7 days, which discourages resolution but does not free the number, and the name is yours for good. See Publishing.
What callers write
import 'package:acme_api/acme_api.dart';
final acme = Acme(ClientConfig(
baseUrl: 'https://api.acme.com/v1',
auth: ClientAuthConfig(bearer: token),
));
// listPaginated is a lazy Stream: await for asks for the next page on demand.
await for (final user in acme.users.listPaginated(limit: 100)) {
print(user.id);
}Parameters are named. Models are plain Dart classes with their own fromJson and toJson, so consumers never run build_runner. Failures throw a subclass of SdkHttpError per common status (SdkNotFoundError, SdkRateLimitError and so on), each carrying statusCode and requestId.
Source maps
Dart minifies for release builds, so production stack traces need source maps uploaded the same way JavaScript does. See Source maps.
Runtime
| Requires | Dart 3.0 or newer |
| HTTP | dart:io HttpClient, so not Flutter web |
| Timeout | 30 seconds per attempt |
| Retries | Up to 3 attempts, with backoff from 500 ms to 8 seconds |
| Idempotency keys | POST and PATCH |
Those are the defaults. See every setting and retries and timeouts to change them.
Streaming
For an operation that streams:
await for (final event in client.events.stream()) {
print(event.id);
}Returns a Stream. See streaming.
Handling errors
try {
await client.users.get_(id: 'usr_1');
} on SdkNotFoundError {
return null;
} on SdkHttpError catch (error) {
print('${error.statusCode} ${error.requestId}');
rethrow;
}Each common status has its own subclass of SdkHttpError. error.data holds the decoded model, which you can narrow with is. get is a reserved word, so that method is get_. See what's in the package.