Top Services
This endpoint allows the client to retrieve a list of top services in the system based on specific query parameters.
The query parameter order_by (String) specifies the ordering criteria for the top services. Clients can choose between
two options:
usage: The services will be sorted based on their overall usage or popularity. The most frequently used services will appear at the top of the list.commission: The services will be sorted based on the commission they generate for the merchant. Services with higher commission rates will appear at the top of the list.
HTTP Method
GET
Endpoint
/api/v1/services/top/
=======
The `services/top/` endpoint allows clients to retrieve a list of top services in the system based on specific query parameters. This endpoint supports two query parameters:
2. `order_by` (String): This parameter specifies the ordering criteria for the top services. Clients can choose between two options: "usage" and "commission."
- If `order_by` is set to "usage," the services will be sorted based on their overall usage or popularity. The most frequently used services will appear at the top of the list.
- If `order_by` is set to "commission," the services will be sorted based on the commission they generate for the merchant. Services with higher commission rates will appear at the top of the list.
## Endpoint URL
https://api.example.com/services/top/
## HTTP Method
GET
## Query Parameters
### `order_by`
- Data Type: String
- Description: Specify the sorting criteria for the top services.
- Possible Values:
- `usage`: Sort services based on their overall usage or popularity.
- `commission`: Sort services based on the commission they generate for the merchant.
- Example: `?order_by=usage`
### `page` & `size`
- Data Type: Integer
- Description: Used to paginate the results where `page` indicates the requested page, and `size` is the number of
records per page
## Response
The API response will include a JSON object containing the list of top services based on the specified query parameters.
Each service entry will contain relevant details, such as:
=======
- Possible Values:
- `usage`: Sort services based on their overall usage or popularity.
- `commission`: Sort services based on the commission they generate for the merchant.
- Example: `?order_by=usage`
## Response
The API response will include a JSON object containing the list of top services based on the specified query parameters. Each service entry will contain relevant details, such as:
- `service`: Service details, including the service ID, name, payment outputs, and receipt footer.
- `provider`: Provider details, including the provider ID ,name.
- `category`: Category details, including the category ID, name, and image.
- `max_commission`: The maximum commission rate for the service.
- `transaction_count`: The total number of transactions for the service.
Example Response:
```json
{
"count": 75,
"next": "https://example.com/api/v1/services/top/?order_by=commission&page=2&size=4",
"previous": null,
"results": [
{
"service": {
"id": 127929,
"name": "دفع فواتير",
"payment_outputs": [
{
"description": "اسم العميل",
"name": "client_name",
"data_type": "str",
"is_hidden": false
},
{
"description": "محل الإقامة",
"name": "location",
"data_type": "str",
"is_hidden": false
},
{
"description": "رقم الفاتورة",
"name": "invoice_number",
"data_type": "float",
"is_hidden": false
},
{
"description": "الرقم المرجعي",
"name": "bill_reference",
"data_type": "str",
"is_hidden": false
}
],
"receipt_footer": ""
},
"provider": {
"id": 6,
"name": "شمال القاهرة"
},
"category": {
"id": 3,
"name": "كهرباء",
"image": "https://mydomain/image1.png"
}
},
{
"service": {
"id": 1271952,
"name": "شحن اورنج",
"payment_outputs": [],
"receipt_footer": ""
},
"provider": {
"id": 78,
"name": "أورنج شحن رصيد"
},
"category": {
"id": 4,
"name": "إتصالات وانترنت",
"image": "https://mydomain/image2.png"
}
},
{
"service": {
"id": 853996,
"name": "Aljazeera 6 month subscription",
"payment_outputs": [],
"receipt_footer": null
},
"provider": {
"id": 89,
"name": "العاب"
},
"category": {
"id": 2,
"name": "ألعاب",
"image": "https://mydomain/image3.png"
}
},
{
"service": {
"id": 2644191,
"name": "Lending Test",
"payment_outputs": [
{
"description": "رقم التاجر",
"name": "merchant_id",
"data_type": "str",
"is_hidden": false
},
{
"description": "تاريخ الدفع",
"name": "repay_date",
"data_type": "str",
"is_hidden": false
},
{
"description": "الرقم القومي",
"name": "national_id",
"data_type": "str",
"is_hidden": false
}
],
"receipt_footer": ""
},
"provider": {
"id": 90,
"name": "تحصيل قروض"
},
"category": {
"id": 87,
"name": "خدمات باي موب",
"image": "https://mydomain/image4.png"
}
}
]
}
"count": 50,
"next": "http://api.example.com/api/v1/services/top/?order_by=usage&page=2",
"previous": null,
"results": [
{
"service": {
"id": 4055677,
"name": "gVAzKbLyIX",
"payment_outputs": [],
"receipt_footer": "Incididunt ab ad nos"
},
"provider": {
"id": 4251,
"name": "tQHkNFVsfN"
},
"category": {
"id": 1,
"name": "Dale Carroll",
"image": "Excepturi dolore nemo dolore cupiditate"
}
},
{
"service": {
"id": 4955548,
"name": "JmpZeiykPY",
"payment_outputs": [],
"receipt_footer": "Incididunt ab ad nos"
},
"provider": {
"id": 8196,
"name": "sandbox"
},
"category": {
"id": 1,
"name": "Dale Carroll",
"image": "Excepturi dolore nemo dolore cupiditate"
}
},
{
"service": {
"id": 4359344,
"name": "wrYIsAEEDw",
"payment_outputs": [],
"receipt_footer": "Incididunt ab ad nos"
},
"provider": {
"id": 6998,
"name": "wQHehMTQux"
},
"category": {
"id": 1,
"name": "Dale Carroll",
"image": "Excepturi dolore nemo dolore cupiditate"
}
},
// Additional service entries...
] }
## Example Usage
### Get Services Ordered by Usage
GET /services/top/?order_by=usage
### Get Top Services for Specific Merchant, Ordered by Commission
GET /services/top/?order_by=commission ```
Notes
- The
order_byparameter is mandatory, and the API will respond with an error if not provided or set to an invalid value. - It is recommended to paginate the results if the list of top services is extensive to enhance performance and reduce data transfer.