Fetching API's with Cubits in Flutter
Tags: flutter, mobile, flutterdev, programming
Published: 2023-09-24 17:18:11

## What are cubits
A Cubit is a simple and efficient way to handle state management in Flutter apps.It's a part of the broader Bloc (Business Logic Component) library, which helps you manage your app's state in a structured and organized manner.

### Here's a breakdown of what a Cubit is:
**State Management**: A Cubit helps you manage the different states your app can be in. This is useful for handling data loading, user interactions, and more.

**Simplicity**: Cubits are designed to be simple and easy to understand. They are a great choice for small to medium-sized applications or when you want to avoid the complexity of full-blown Blocs.

**Events and States**: In a Cubit, you define a series of events that can trigger state changes. For example, you might have an event to fetch data from an API, and the Cubit can have states like "loading," "success," or "error" to represent the various stages of the data-fetching process.

**UI Integration**: Cubits update the user interface based on changes in state. This ensures that your app's UI always reflects the current state of your Cubit.


## Project Setup
We're going to hit the [json placeholder API](https://jsonplaceholder.typicode.com/users) and display the list of users in our app.We'll use the [dio](https://pub.dev/packages/dio) package for handling the network request.

### 1.Add Dependencies
In your `pubspec.yaml` file, include these packages under the  dependencies:
- `bloc`  and `flutter_bloc` packages for state management 
- `dio` package for making HTTP requests
- `freezed_annotation` for auto-generating Cubit states
- `json_annotation` for generation of json de/serialization methods

```
dependencies:
  flutter:
    sdk: flutter
  bloc: ^8.1.2
  flutter_bloc: ^8.1.3
  dio: ^5.3.3
  freezed_annotation: ^2.4.1
  json_annotation: ^4.8.1
```
### 2.Add the dev dependencies
Also add these packages under the dev_dependencies.They help with code generation for the cubits and also with json serialization.

```
dev_dependencies:
  freezed: ^2.4.2
  json_serializable: ^6.7.1
  build_runner: ^2.4.6
```

### 3.Project Structure
This is how we will structure our files for easy maintainability.

```
your_project_name/
  lib/
    cubits/
      users_cubit.dart 
      users_states.dart
    models/
      user.dart         
    screens/
      users_page.dart
    main.dart
```

## Creating the user model
In the `lib/models/user.dart` file,create a freezed `User` class.

The **@freezed** annotation is used to generate the boilerplate code for the `User` class. This includes the constructor, `copyWith` method, `toString` method, and operator== method.
```
part 'user.freezed.dart';
part 'user.g.dart';

@freezed
class User with _$User {
  const factory User({
    required int id,
    required String name,
    required String username,
    required String email,
    required String phone,
    required String website,
  }) = _User;

  factory User.fromJson(Map<String,dynamic> json) => _$UserFromJson(json);
}
```

The User class also includes a `fromJson` factory method that is used to create a new instance of the `User` class from a JSON object. This method is generated using the `json_serializable` package, which is a companion package to `freezed_annotation`.

After doing that you can run this command in your terminal to generate the code:
```
dart run build_runner build --delete-conflicting-outputs
```

## Creating UserStates
In the `lib/cubits/users_states.dart` we create a `UserStates` class.
The `UserStates` class is used to represent the different states that the `User` list can have in our application,that is, `initial` state,`loading` state,`error` state and `success` state.

The class is also marked with the **@freezed** annotation to generate the boilerplate code for the Cubit.

```
part of 'users_cubit.dart';

@freezed
class UsersState with _$UsersState {
  const factory UsersState.initial() = _Initial;
  const factory UsersState.loading() = _Loading;
  const factory UsersState.success(List<User> users) = _Success;
  const factory UsersState.error(String errorMessage) = _Error;

}

```
After this you can run the build_runner command above,to autogenerate the methods and remove the errors.

## Creating the User Cubit
After defining all the possible states that our app can have,it's time to bring everything in order - that's what a cubit basically does.

First create a UsersCubit class that extends Cubit from the bloc package:

```
part 'users_state.dart';
part 'users_cubit.freezed.dart';

class UsersCubit extends Cubit<UsersState> {
  UsersCubit() : super(const UsersState.initial());
}
```
The cubit should initally contain an instance of  UsersState.initial() passed in it's constructor, which is the initial state before the API calls begin to happen.

Next,we will define a method fetchUsers() in which we will contact the API:

```
    fetchUsers() async {
    try {
      emit(const UsersState.loading());
      Dio dio = Dio();

      final res = await dio.get("https://jsonplaceholder.typicode.com/users");
      if (res.statusCode == 200) {
        final users = res.data.map<User>((item) {
          return User.fromJson(item);
        }).toList();

        emit(UsersState.success(users));
      } else {
        emit(
          UsersState.error("Error loading users: ${res.data.toString()}"),
        );
      }
    } catch (e) {
      emit(
        UsersState.error("Error loading users: ${e.toString()}"),
      );
    }
  }
```

1. The `fetchUsers` method first emits a `UsersState.loading()` state to indicate that the user list is being loaded
2. The Dio package is used to make an HTTP GET request to the remote API
3. If the response status code is 200, the response data is mapped to a list of User objects using the `fromJson` factory method of the User class. The success state is then emitted with the list of User objects.
4. If the response status code is not 200, the error state is emitted with an error message that includes the response data.
5. If an exception is thrown while making the HTTP request or mapping the response data, the error state is emitted with an error message that includes the exception message.

The method should be writen inside of the `UsersCubit` class. For better and cleaner code,the API call would be separated in a repository file but let's just keep it simple for now.

This is how the cubit finally looks like:

```
part 'users_state.dart';
part 'users_cubit.freezed.dart';

class UsersCubit extends Cubit<UsersState> {
  UsersCubit() : super(const UsersState.initial());

  fetchUsers() async {
    try {
      emit(const UsersState.loading());
      Dio dio = Dio();

      final res = await dio.get("https://jsonplaceholder.typicode.com/users");
      if (res.statusCode == 200) {
        final users = res.data.map<User>((item) {
          return User.fromJson(item);
        }).toList();

        emit(UsersState.success(users));
      } else {
        emit(
          UsersState.error("Error loading users: ${res.data.toString()}"),
        );
      }
    } catch (e) {
      emit(
        UsersState.error("Error loading users: ${e.toString()}"),
      );
    }
  }
}
```
Make sure you import all the necessary packages into the file

## Building the UI
Now it's time to consume our `UsersCubit` from the UI and show the different states as defined.

### 1.Add BlocProvider in MaterialApp
In the `lib/main.dart` file at the root MyApp class,we shall have the  MaterialApp() class,whose home property will be a **BlocProvider()**.

A **BlocProvider** takes in a `create` function,that is responsible for creating an instance of a Cubit and a `child` Widget which will have access to that instance through it's context.

```
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        useMaterial3: true,
      ),
      home: BlocProvider(
        create: (context)=> UsersCubit(),
        child: const UsersPage(),
      ),
    );
  }
}
```

### 2.Create Users page with a BlocBuilder
We then create a Stateless Widget called `UsersPage` in the `lib/screens/users_page.dart` file.The page has a simple AppBar and for the body we use a BlocBuilder.

BlocBuilder takes in a cubit(UsersCubit in our case) and a state(UsersState).It then handles the building of a widget in response to the cubit's current state.

```
class UsersPage extends StatelessWidget {
  const UsersPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        centerTitle: true,
        title: const Text("Users"),
      ),
      body: BlocBuilder<UsersCubit, UsersState>(
        builder: (context, state) {
         //UI is built per the state
        },
      ),
    );
  }
}
```

### 3.Building UI for different states.
The builder function has a **state.when** method which is used to handle the different states of the `UsersCubit`:

```
      body: BlocBuilder<UsersCubit, UsersState>(
        builder: (context, state) {
          return state.when(
            initial: () => Center(
              child: ElevatedButton(
                child: const Text("Get Users"),
                onPressed: () => context.read<UsersCubit>().fetchUsers()
              ),
            ),
            loading: () => const Center(
              child: CircularProgressIndicator(),
            ),
            error: ((errorMessage) => Center(child: Text(errorMessage),)),
            success: (users) {
              return ListView.builder(
                itemCount: users.length,
                itemBuilder: (context, index) {
                  return ListTile(
                    title: Text(users[index].name),
                    subtitle: Text(users[index].email),
                  );
                },
              );
            },
          );
        },
      ),
```

1. If the state is `initial`, a Center widget with an ElevatedButton is returned. If the button is pressed, the `fetchUsers` method of the `UsersCubit` is called to load the user list.
2. If the state is `loading`, a Center widget with a CircularProgressIndicator is returned to indicate that the user list is being loaded.
3. If the state is `error`, a Center widget with a Text widget that displays the error message is returned.
4. If the state is `success`, a ListView.builder widget is returned to display the list of users.



With that,all the states in our cubit are taken care of effectively.
**_Initial State_**
![Initial State](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9a3sbfrorhm7hio8i760.png) 
**_Loading State_**

![Loading state](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x7rfo7b3dkhd5wal27cb.png)
**_Success State_**

![ISucess state - List of users](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fa3k2hokpvo4ph9ys5o4.png)
**_Error State_**

![Error state](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lnjhmz0w5y7djtjuteaf.png)

## Wrap up
With Cubits you just have to define your states then show the different UI's based on the current state of that cubit,that simple💯

You can check the [Github Repo](https://github.com/dev-vickie/learning-cubits) for the whole code.

Happy Coding!