Requests

Available Request annotations

Annotation	HTTP verb	Description
@GET(), @get	GET	Defines a GET request.
@POST(), @post	POST	Defines a POST request.
@PUT(), @put	PUT	Defines a PUT request.
@PATCH(), @patch	PATCH	Defines a PATCH request.
@DELETE(), @delete	DELETE	Defines a DELETE request.
@HEAD(), @head	HEAD	Defines a HEAD request.
@OPTIONS(), @options	OPTIONS	Defines an OPTIONS request.
@QUERY(), @httpQuery	QUERY	Defines a QUERY request with content.
@Path(), @path	-	Defines a dynamic path parameter.
@Body(), @body	-	Defines the request's body.
@Header(), @header	-	Defines a dynamic request header.
@FormUrlEncoded(), @formUrlEncoded	-	Defines an application/x-www-form-urlencoded request.
@Multipart(), @multipart	-	Defines a multipart/form-data request.
@Query(), @query	-	Defines a query parameter.
@QueryMap(), @queryMap	-	Defines a query parameter map.
@FactoryConverter(), @factoryConverter	-	Defines a request/response converter factory.
@Field(), @field	-	Defines a form field.
@FieldMap(), @fieldMap	-	Defines a form field map.
@Part(), @part	-	Defines a multipart part.
@PartMap(), @partMap	-	Defines a multipart part map.
@PartFile(), @partFile	-	Defines a multipart file part.
@PartFileMap(), @partFileMap	-	Defines a multipart file part map.
@Tag(), @tag	-	Defines a tag parameter.
@AbortTrigger(), @abortTrigger	-	Defines a request cancellation trigger.

HTTP QUERY requests

Chopper supports the HTTP QUERY method defined by RFC 10008. QUERY is a safe, idempotent method with request content; it is not a GET request with a body.

Use @QUERY with @Body() in a generated service:

@ChopperApi(baseUrl: '/resources')
abstract class ResourceService extends ChopperService {
  @QUERY(path: '/search', headers: {contentTypeKey: jsonHeaders})
  Future<Response<Map<String, dynamic>>> searchResources(
    @Body() Map<String, dynamic> query,
  );
}

For a request without method options, use @httpQuery as a shorthand for @QUERY(). The existing @query annotation continues to define a URL query parameter.

The request must include a Content-Type consistent with its content. Chopper delegates redirects, retries, caching, and CORS behavior to the configured http.Client. Cross-origin browser requests require a CORS preflight that permits QUERY, and Dart's default native client does not automatically follow QUERY redirects.

See the runnable package example for a complete request.

Path resolution

Chopper handles paths passed to HTTP verb annotations' path parameter based on the path's content.

If the path value is a relative path, it will be concatenated to the URL composed of the baseUrl of the ChopperClient and the baseUrl of the enclosing service class (provided as a parameter of the @ChopperApi annotation).

Here are a few examples of the described behavior:

Variable	URI
base URL	https://example.com/
Path	profile
Result	https://example.com/profile

Variable	URI
base URL	https://example.com/
Service base URL	profile
Path	/image
Result	https://example.com/profile/image

Variable	URI
base URL	https://example.com/
Service base URL	profile
Path	image
Result	https://example.com/profile/image

Chopper detects and handles missing slash (/) characters on URL segment borders, but does not handle duplicate slashes.

If the service's baseUrl concatenated with the request's path results in a full URL, the ChopperClient's baseUrl is ignored.

Variable	URI
base URL	https://example.com/
Service base URL	https://api.github.com/
Path	user
Result	https://api.github.com/user

A path containing a full URL replaces the base URLs of both the ChopperClient and the service class entirely for a request.

Variable	URI
base URL	https://example.com/
Path	https://api.github.com/user
Result	https://api.github.com/user

Variable	URI
base URL	https://example.com/
Service base URL	profile
Path	https://api.github.com/user
Result	https://api.github.com/user

Path parameters

Dynamic path parameters can be defined in the URL with replacement blocks. A replacement block is an alphanumeric substring of the path surrounded by { and }. In the following example {id} is a replacement block.

@GET(path: "/{id}")

Use the @Path() annotation to bind a parameter to a replacement block. This way the parameter's name must match a replacement block's string.

@GET(path: "/{id}")
Future<Response> getItemById(@Path() String id);

As an alternative, you can set the @Path annotation's name parameter to match a replacement block's string while using a different parameter name, like in the following example:

@GET(path: "/{id}")
Future<Response> getItemById(@Path("id") int itemId);

Chopper uses String interpolation to replace replacement blocks with the provided values in the request URLs.

Query parameters

Dynamic query parameters can be added to the URL by adding parameters to a request method annotated with the @Query annotation. Default values are supported.

Future<Response> search(
    @Query() String name, {
    @Query("count") int numberOfResults = 42,
});

If the parameter of the @Query annotation is not set, Chopper will use the actual name of the annotated parameter as the key for the query parameter in the URL.

If you prefer to pass a Map of query parameters, you can do so with the @QueryMap annotation.

Future<Response> search(@QueryMap() Map<String, dynamic> query);

Chopper encodes nested query maps and iterables with qs_dart. Repeated query parameters are the default list format:

@GET(path: "/search")
Future<Response> search(@Query("tag") List<String> tags);

await service.search(["dart", "http"]);
// /search?tag=dart&tag=http

Use the HTTP method annotation's listFormat, dateFormat and includeNullQueryVars options when an endpoint needs different query encoding:

@GET(
  path: "/events",
  listFormat: ListFormat.brackets,
  dateFormat: DateFormat.date,
  includeNullQueryVars: true,
)
Future<Response> events({
  @Query("days") List<int?> days = const [1, null, 3],
  @Query("from") required DateTime from,
});

If a query value needs custom serialization before the URL is encoded, configure a ParameterConverter on the ChopperClient, or use a client converter that also implements ParameterConverter. Parameter conversion currently applies to query values only; query keys are left unchanged.

Request body

Use the @Body annotation on a request method parameter to specify data that will be sent as the request's body.

@POST(path: "todo/create")
Future<Response> postData(@Body() String data);

Chopper does not automatically convert Objects to Map and then JSON.

You have to pass a Converter instance to a ChopperClient for JSON conversion to happen. See built_value_converter for an example Converter implementation.

Headers

Request headers can be set by providing a Map<String, String> object to the headers parameter each of the HTTP verb annotations have.

@GET(path: "/", headers: {"foo": "bar"})
Future<Response> fetch();

The @Header annotation can be used on method parameters to set headers dynamically for each request call.

@GET(path: "/")
Future<Response> fetch(@Header("foo") String bar);

Setting request headers dynamically is also supported by Interceptors and Converters.

As Chopper invokes Interceptors and Converter(s) after creating a Request, Interceptors and Converters can override headers set with the headers parameter or @Header annotations.

Sending application/x-www-form-urlencoded data

If no converter is specified for a request (neither on the ChopperClient nor with @FactoryConverter) and the request body is a Map<String, String>, the body will be sent as form URL encoded data.

This is the default behavior of the http package.

FormUrlEncoded annotation

Use @FormUrlEncoded() or @formUrlEncoded on a method to add the correct content-type and convert a Map into Map<String, String> for requests.

@POST(path: "form")
@FormUrlEncoded()
Future<Response> postForm(@Body() Map<String, String> fields);

FormUrlEncodedConverter

You can also use FormUrlEncodedConverter to add the correct content-type and convert a Map into Map<String, String> for requests.

final chopper = ChopperClient(
  converter: FormUrlEncodedConverter(),
);

To do only a single type of request with form encoding in a service, use the provided FormUrlEncodedConverter.requestFactory method with the @FactoryConverter annotation.

@POST(
  path: "form",
  headers: {contentTypeKey: formEncodedHeaders},
)
@FactoryConverter(request: FormUrlEncodedConverter.requestFactory)
Future<Response> postForm(@Body() Map<String, String> fields);

Defining fields individually

To specify fields individually, use the @Field annotation on method parameters. If the field's name is not provided, the parameter's name is used as the field's name.

@POST(path: "form")
@FormUrlEncoded()
Future<Response> post(@Field() String foo, @Field("b") int bar);

Sending files with @Multipart

Sending a file in bytes as List<int> using @PartFile

@POST(path: 'file')
@Multipart()
Future<Response> postFile(@PartFile('file') List<int> bytes);

Sending a file as MultipartFile using @PartFile with extra parameters via @Part

@POST(path: 'file')
@Multipart()
Future<Response> postMultipartFile(
  @PartFile() MultipartFile file,
  {
    @Part() String? id,
  },
);

Sending multiple files as List<MultipartFile> using @PartFile

@POST(path: 'files')
@Multipart()
Future<Response> postListFiles(@PartFile() List<MultipartFile> files);

Defining responses

ChopperService methods need to return a Future. It is possible to define return types of Future<Response> or Future<Response<T>> where T is the type of the response body. When Response is not needed for a request, it is also possible to define a return type of Future<T> where T is the type of the response body.

Chopper will generate a client which returns the specified return type. When the method does not directly return Response, Chopper returns response.bodyOrThrow; unsuccessful responses throw the response error when it is an Exception, otherwise a ChopperHttpException. A successful response whose converted body is null also throws a ChopperHttpException; use Future<Response<T>> and read response.body directly for endpoints where a successful null body is expected, such as HTTP 204/no-content responses.

// Returns a Response<dynamic>
@GET(path: "/")
Future<Response> fetch();

// Returns a Response<MyClass>
@GET(path: "/")
Future<Response<MyClass>> fetch();

// Returns a MyClass
@GET(path: "/")
Future<MyClass> fetch();

Note: Chopper doesn't convert response bodies by itself to Dart objects. You need to use a Converter for that.

Add tag

Use the @Tag() parameter annotation to set request.tag on the underlying Chopper Request. Tags can be read in Converters or Interceptors for tracing, analytics, varying behavior, and more.

For example, a converter can use a tag to decide whether null or empty body values should be included for one request.

class IncludeBodyNullOrEmptyTag {
  const IncludeBodyNullOrEmptyTag({
    this.includeNull = false,
    this.includeEmpty = false,
  });

  final bool includeNull;
  final bool includeEmpty;
}

@GET(path: '/include')
Future<Response> includeBodyNullOrEmptyTag({
  @Tag() IncludeBodyNullOrEmptyTag tag = const IncludeBodyNullOrEmptyTag(),
});

Read the tag via request.tag in a Converter or Interceptor:

class TagConverter extends JsonConverter {
  @override
  Request convertRequest(Request request) {
    final tag = request.tag;
    if (tag is IncludeBodyNullOrEmptyTag) {
      if (request.body is Map) {
        final Map body = request.body as Map;
        final Map bodyCopy = {};
        for (final MapEntry entry in body.entries) {
          if (!tag.includeNull && entry.value == null) continue;
          if (!tag.includeEmpty && entry.value == "") continue;
          bodyCopy[entry.key] = entry.value;
        }
        request = request.copyWith(body: bodyCopy);
      }
    }
    return super.convertRequest(request);
  }
}