prestashop_api

Description:

prestashop api

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!
Index #

Motivation
Index
Features
Quickstart

1. Add to pubspec.yaml
2. Import the package
3. Set the base configuration
4. Initialize PrestashopApi
5. Call a PrestaShop API


Options

1. Display Fields
2. Filtering Data
3. Sorting Data


More Features

1. Predefined Models
2. Implicit Serialization / Deserialization
3. Enhanced Query Precision

Challenges
Solutions


4. Addressing Pagination Limitations
5. Predefined tailored exceptions


Example using PrestashopApi
Available API Requests

PrestaShop - Categories
PrestaShop - Languages
PrestaShop - Products
PrestaShop - Stock Availables


PrestaShop API Documentation Reference
Feedback
Disclaimer

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
copied to clipboard
2. Import the package #
import 'package:prestashop_api/prestashop_api.dart';
copied to clipboard
3. Set the base configuration #
final baseConfig = BaseConfig(
baseUrl: 'www.your-website.com',
apiKey: 'YOUR-API-KEY-XXXXXXXXX',
protocol: Protocol.https,
);
copied to clipboard
4. Initialize PrestashopApi #
final prestashop = PrestashopApi(baseConfig);
copied to clipboard
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);
copied to clipboard
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');
}
copied to clipboard
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,
],
);
copied to clipboard
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',
);
copied to clipboard
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),
]);
copied to clipboard
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');
}
}
copied to clipboard
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.

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter