PrestaShop API Dart package #

Motivation #

The story of this package began with a simple need: to seamlessly bridge a Flutter app with a PrestaShop website. I found that existing packages were insufficient because, even after integrating any of them, I still needed to:

Create model classes to mirror API entities.
Deal with data de/serialization.
Manually construct API requests.
Address the pagination feature limitation in the API.
Figure out API errors and create tailored exceptions.
...

Implementing all of these tasks can result in hundreds of lines of code, increasing the likelihood of errors. These main factors drove me to create the prestashop_api package from scratch.

prestashop_api package alleviates most of those burdens by implementing much of this for you, allowing you to focus more on your app's functionalities.

Let's explore the package's capabilities together!

Features #

Localized Field Display: Display localized fields in a specified language.
Field Display Options: Choose to display specific fields or all fields.
Filtering Data: Filter data using various methods.
Sorting Data: Sort data based on specified fields and order.
Limiting Results and Pagination: Limit the number of returned results, as a total number and starting from a specific page.
And much more...

Quickstart #

An example speaks volumes compared to a lengthy abstract explanation, so here's a typical request to fetch products:

1. Add to pubspec.yaml #

dependencies:
  prestashop_api: ^0.1.1

2. Import the package #

  import 'package:prestashop_api/prestashop_api.dart';

3. Set the base configuration #

  final baseConfig = BaseConfig(
    baseUrl: 'www.your-website.com',
    apiKey: 'YOUR-API-KEY-XXXXXXXXX',
    protocol: Protocol.https,
  );

4. Initialize PrestashopApi #

  final prestashop = PrestashopApi(baseConfig);

Optionally, you can configure the Dio property of the PrestashopApi instance:

  // E.g., set a custom `connectTimeout` of Dio
  final customDio = Dio();
  prestashop.dio = customDio..options.connectTimeout = const Duration(seconds: 5);

5. Call a PrestaShop API #

  try {
    // E.g., GET all products in the primary language
    final receivedProducts = await prestashop.getProducts(languageId: 1);

    // Print the products payload in a pretty structured JSON
    prettyPrint<Product>(
      tagText: 'Print all products',
      data: receivedProducts.entity,
      toJsonMap: productToJsonMap,
    );
  } catch (e) {
    print('Exception caught: $e');
  }

Options #

When calling the PrestaShop API, you can pass various options:

1. Display Fields #

You have the option to "display" either specific fields or all fields. If no fields are specified, the API will return the default fields it defines.

  // Display `id` and `name` fields for products display
  const display = Display(
    displayFieldList: [
      ProductDisplayField.id,
      ProductDisplayField.name,
    ],
  );

  //
  // Alternatively
  //
  
  // Display all available fields of products
  const display = Display(
    displayFieldList: [
      ProductDisplayField.all,
    ],
  );

2. Filtering Data #

Refine the expected result using the "filter" parameter. Below are exhaustive examples for each filter method:

  // Filter products by matching any of the specified values
  final filter = Filter.anyOf(
    ProductFilterField.id,
    values: ['1', '5'],
  );

  // Filter products by specifying an interval between two values
  final filter = Filter.between(
    ProductFilterField.id,
    begin: '1',
    end: '10',
  );

  // Filter products by exact value (case insensitive)
  final filter = Filter.equals(
    ProductFilterField.name,
    value: 'Wheels',
  );

  // Filter products by value prefix (case insensitive)
  final filter = Filter.beginsWith(
    ProductFilterField.name,
    value: 'Whe',
  );

  // Filter products by value suffix (case insensitive)
  final filter = Filter.endsWith(
    ProductFilterField.name,
    value: 'els',
  );

  // Filter products by value contained within (case insensitive)
  final filter = Filter.contains(
    ProductFilterField.name,
    value: 'eel',
  );

3. Sorting Data #

Utilize the "sort" parameter to organize the expected result according to your preferences.

  // Sort products based on `id` in descending order
  final sort = Sort(
    sortFieldOrderList: [
      SortField.descending(ProductSortField.id),
    ],
  );

  //
  // Alternatively
  //

  // Sort products based on `id` in ascending order
  final sort = Sort([
    SortField.ascending(ProductSortField.id),
  ]);

More Features #

But wait, there's more! prestashop_api still has a host of additional features up its sleeve.

1. Predefined Models #

prestashop_api offers prebuilt model classes that mirror PrestaShop API entities. You can use these models instantly, eliminating the need to create them manually.

2. Implicit Serialization / Deserialization #

Effortlessly retrieve and manage data from the PrestaShop API. prestashop_api handles serialization and deserialization for you, enabling seamless conversion of data between Dart objects and JSON representations.

3. Enhanced Query Precision #

Challenges

Writing queries the traditional way, poses two main challenges:

Limited Field Support Not all fields in the PrestaShop API support display, filtering, and sorting functionalities. This increases the risk of selecting the wrong fields and causes API error responses.
Complex Syntax Implementing display, filtering, and sorting functionalities in URL queries requires adherence to specific structuring rules. Failure to follow these conventions can lead to API error responses.

Solutions

To address these challenges, prestashop_api provides:

Built-in Functionality Fields Predefined fields for display, filtering, and sorting for every supported resource ensure precise query construction without the risk of selecting unsupported fields.
Standardized Syntax Predefined syntax for implementing functionalities simplifies query construction, reduces syntax errors, and enhances overall query precision and reliability.

4. Addressing Pagination Limitations #

The pagination feature in the PrestaShop v1.7 API lacks information about the maximum page number in the response headers, making it difficult to determine the availability of a next page in paginated data requests. To address this limitation, prestashop_api provides a straightforward solution. In the response of the fetch method, you can simply check the boolean 'isNextPageAvailable' to determine if a next page is available. To see the simplicity of integrating this feature in your code, please consult the following example.

5. Predefined tailored exceptions #

prestashop_api offers a wide range of predefined exceptions, tailored for the PrestaShop API. Save time with ready-to-use exceptions for common errors and unique scenarios, allowing you to focus on building robust applications confidently.

Example using PrestashopApi #

// This file is "main.dart"
import 'package:prestashop_api/prestashop_api.dart';

Future<void> main() async {
  // Configure your `BaseConfig`
  final baseConfig = BaseConfig(
    baseUrl: 'www.your-website.com',
    apiKey: 'YOUR-API-KEY-XXXXXXXXX',
    protocol: Protocol.https,
  );

  // Initialize `PrestashopApi` with base configuration
  final prestashop = PrestashopApi(baseConfig);

  // Specify the product fields to display, such as 'id' and 'name'. If left empty, only IDs will 
  // be displayed by default
  const display = Display(
    displayFieldList: [
      ProductDisplayField.id,
      ProductDisplayField.name,
    ],
  );

  // Set filter to fetch products with IDs from 1 to 20
  final filter = Filter.between(
    ProductFilterField.id,
    begin: '1',
    end: '20',
  );

  // Sort products by name in descending order
  final sort = Sort(
    sortFieldOrderList: [
      SortFieldOrder.descending(ProductSortField.name),
    ],
  );

  try {
    // Fetch products with specified parameters using pagination
    final receivedProducts = await prestashop.getProductsPage(
      // Required property: Set the language ID for product data retrieval
      languageId: 1,
      // Required property: page number
      page: 2,
      // Required property: products count per page
      perPage: 10,
      // Optional properties: filter, display, and sort functionalities
      filter: filter,
      display: display,
      sort: sort,
    );
    
    print('A next page is available: ${receivedProducts.isNextPageAvailable}');

    // Print retrieved product data in a well formatted way
    prettyPrint<Product>(
      tagText: 'Products with IDs ranging from 11 to 20',
      data: receivedProducts.entity,
      toJsonMap: productToJsonMap,
    );
  } catch (e) {
    // Handle errors
    print('Error caught: $e');
  }
}

Available API Requests #

Below are the current supported API requests. Please note that the development of the package is ongoing, and additional API requests may be added in future updates.

PrestaShop - Categories #

Get Categories
Retrieve a Category by id
Get Categories by page

See Categories API

PrestaShop - Languages #

Get Languages
Retrieve a Language by id
Get Languages by page

See Languages API

PrestaShop - Products #

Get Products
Retrieve a Product by id
Get Products by page

See Products API

PrestaShop - Stock Availables #

Get Stock Availables
Retrieve a Stock Available by id
Get Stock Availables by page

See Stock Availables API

PrestaShop API Documentation Reference #

PrestaShop Docs

Feedback #

For bugs or feature requests, please use the issue tracker.

Disclaimer #

This package is not affiliated with or supported by PrestaShop, "www.prestashop.com". All logos and trademarks are the property of their respective owners.

Licensing #

This project is licensed under "The 3-Clause BSD License". See LICENSE for more information.

prestashop_api 0.1.1 prestashop_api: ^0.1.1 copied to clipboard

Metadata