Getting started

📚
Chopper
Search…
📚
Converters
Built Value Converter
Getting started
How does Chopper work?
Due to limitations to Dart on Flutter and the Web browser, Chopper doesn't use reflection but code generation with the help of the build and source_gen packages from the Dart Team.
Installation
Add the chopper and the chopper_generator packages to your project dependencies.
1
# pubspec.yaml
2
​
3
dependencies:
4
  chopper: ^3.0.7
5
​
6
dev_dependencies:
7
  build_runner: ^1.12.1
8
  chopper_generator: ^3.0.7
Copied!
Run pub get to start using Chopper in your project.
Define your API
ChopperApi
To define a client, use the @ ChopperApi annotation on an abstract class that extends the ChopperService class.
1
// YOUR_FILE.dart
2
​
3
import "dart:async";
4
import 'package:chopper/chopper.dart';
5
​
6
// This is necessary for the generator to work.
7
part "YOUR_FILE.chopper.dart";
8
​
9
@ChopperApi(baseUrl: "/todos")
10
abstract class TodosListService extends ChopperService {
11
​
12
  // A helper method that helps instantiating the service. You can omit this method and use the generated class directly instead.
13
  static TodosListService create([ChopperClient client]) => 
14
      _$TodosListService(client);
15
}
Copied!
The @ChopperApi annotation takes one optional parameter - the baseUrl - that will prefix all the request's URLs defined in the class.
There's an exception from this behavior described in the Requests section of the documentation.
Defining a request
Use one of the following annotations on abstract methods of a service class to define requests:
@Get
@Post
@Put
@Patch
@Delete
@Head
Request methods must return with values of the type Future<Response> or Future<Response<SomeType>>.
To define a GET request to the endpoint /todos in the service class above, add one of the following method declarations to the class:
1
@Get()
2
Future<Response> getTodos();
Copied!
or
1
@Get()
2
Future<Response<List<Todo>>> getTodos();
Copied!
URL manipulation with dynamic path, and query parameters is also supported. To learn more about URL manipulation with Chopper, have a look at the Requests section of the documentation.
Defining a ChopperClient
After defining one or more ChopperServices, you need to bind instances of them to a ChopperClient. The ChopperClient provides the base URL for every service and it is also responsible for applying interceptors and converters on the requests it handles.
1
import "dart:async";
2
import 'package:chopper/chopper.dart';
3
​
4
import 'YOUR_FILE.dart';
5
​
6
void main() async {
7
  final chopper = ChopperClient(
8
      baseUrl: "http://my-server:8000",
9
      services: [
10
        // Create and pass an instance of the generated service to the client
11
        TodosListService.create()
12
      ],
13
    );
14
​
15
  /// Get a reference to the client-bound service instance...
16
  final todosService = chopper.getService<TodosListService>();
17
  /// ... or create a new instance by explicitly binding it to a client.
18
  final anotherTodosService = TodosListService.create(chopper);
19
​
20
  /// Making a request is as easy as calling a function of the service.
21
  final response = await todosService.getTodos();
22
​
23
  if (response.isSuccessful) {
24
    // Successful request
25
    final body = response.body;
26
  } else {
27
    // Error code received from server
28
    final code = response.statusCode;
29
    final error = response.error;
30
  }
31
}
Copied!
Handling I/O and other exceptions should be done by surrounding requests with try-catch blocks.
Chopper
Requests
Last modified 1yr ago
Copy link
Contents
How does Chopper work?
Defining a ChopperClient