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
- Options
- More Features
- Example using PrestashopApi
- Available API Requests
- 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
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
PrestaShop - Languages
- Get Languages
- Retrieve a Language by id
- Get Languages by page
PrestaShop - Products
- Get Products
- Retrieve a Product by id
- Get Products by page
PrestaShop - Stock Availables
- Get Stock Availables
- Retrieve a Stock Available by id
- Get Stock Availables by page
PrestaShop API Documentation Reference
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.
Libraries
- prestashop_api
- You can make APIs public here.