http_services 2.1.1
http_services: ^2.1.1 copied to clipboard

A Dart package based on Dio that provides base models to handle HTTP services requests.

http_services #

A package to support the creation of Http services in a Dart application.

Features #

  • convenient methods to perform HTTP requests
  • disposing a service will cleanup any pending requests, in order to avoid unwanted resources waste!
  • convenient models to have a standard for request and response objects

RequestBase #

Every request should extend RequestBase and implement its overrides:

  • endpoint: Specify the path of the request
  • toJson: This method is used for the request's serialization
  • toData: This is an optional override in case you need to post a non JSON body. It returns an object of type T.

By default toData returns null

ResponseBase #

Every response should extend ResponseBase

Exceptions #

All the exceptions of this package extend HttpServiceException

ApiException: #

This is thrown when something is wrong with the request (e.g. missing internet, resource not found, etc).

  • networkError signals if there was an outage in connection
  • httpCode is the received HTTP status code
  • httpMessage is the received HTTP status message

UnexpectedStatusCodeException: #

This is thrown when expected HTTP code doesn't match the received one.

  • expected is the expected status code
  • actual is the received status code

ResponseMappingException: #

This is thrown when an error occurs while mapping the response.

RequestCanceledException: #

This is thrown when a request is canceled.

HttpServiceBase #

Every service should extend this.

To make a request within you service, you can use one of the following:

  • getQuery: perform a GET request
  • postData: perform a POST request
  • postJson: perform a POST request with a JSON body
  • putData: perform a PUT request
  • putJson: perform a PUT request with a JSON body
  • deleteData: perform a DELETE request
  • deleteJson: perform a DELETE request with a JSON body
  • patchData: perform a PATCH request
  • patchJson: perform a PATCH request with a JSON body
  • download: downloads a file
  • getBytes: gets bytes from an endpoint

Example #

import 'package:dio/dio.dart';
import 'package:http_services/http_services.dart';

import 'todos_service.dart';

class TodosRequest extends RequestBase {
  final int page;

  TodosRequest( : assert(page != null && page > 0);
  String get endpoint => '/todos/$page';

  Map<String, dynamic> toJson() {
    return {};

class TodosResponse extends ResponseBase {
  final int userId;
  final int id;
  final String title;
  final bool completed;


  factory TodosResponse.fromJson(Map<String, dynamic> json) => TodosResponse(
        userId: json['userId'],
        id: json['id'],
        title: json['title'],
        completed: json['completed'],

class TodosService extends HttpServiceBase {
  TodosService(Dio dioInstance) : super(dioInstance);

  Future<TodosResponse> getTodo(int page) {
    final request = TodosRequest(page);

    return getQuery(
      request: request,
      mapper: (json, _) => TodosResponse.fromJson(json),

void main() async {
  final dio = Dio(
      baseUrl: '',

  final service = TodosService(dio);

  try {
    print("Requesting data...");
    final response1 = await service.getTodo(1);
      "user id: ${response1.userId}\n"
      "id: ${}\n"
      "title: ${response1.title}\n"
      "completed: ${response1.completed}",
  } on HttpServiceException catch (e) {
    print('Service exception: ${e.runtimeType}');

Notes #

There might be some cases where the JSON response is not like this:

  "data": [{"name": "Bob"},{"name":"Alice"}],

This will not be treated as a JSON since it's not a Map<String,dynamic> but it's a List<Map<String,dynamic>>. A solution might be to use the orElse parameter when performing the HTTP request. Remember that orElse is executed to map any response body that's not Map<String,dynamic>.

Similarly, if you ever find yourself in need of sending a JSON like the one above, a solution might be to override the onData method of RequestBase in your request object and then using the *data version of the request. For example:

class User{
  final String name;

  Map<String,dynamic> toJson() => {'name': name};

class UsersToSend extends RequestBase{
  final List<User> users;

  Map<String,dynamic> toJson() => {};

  List<User> toData() => users;

and then use postData instead of using postJson in your service.

Contributors 🚀 #

pub points


A Dart package based on Dio that provides base models to handle HTTP services requests.

Repository (GitHub)
View/report issues


API reference




dio, disposable_object, meta


Packages that depend on http_services