FE/BE Communication Requirements

"In quoting others, we cite ourselves." — Julio Cortazar

Document Metadata

Field	Value
Version	1.0.0
Last Updated	January 15, 2025
Owner	Mohamed Wagih
Status	✅ Approved
Type	Process

---

Purpose

Ensure a smooth and error-free development process for features that require both Frontend and Backend collaboration.

Scope

This document covers the communication guidelines and standards for the Frontend and Backend Teams in the context of sending and receiving data and filters through APIs.

Audience

This document targets the Frontend and Backend Teams.

---

RACI Chart

The RACI chart identifies roles and lines of accountability clearly:

• Responsible – who completes this procedure
• Accountable – who reviews this procedure
• Consulted – who is consulted in this procedure
• Informed – who needs to be notified of this procedure

R	A	C	I
Mohamed Wagih	Mohamed Khalil	Omar Atallah	Ahmed EID
Muhammed Kamal	Frontend	Backend	Mobile

---

Tools Needed

• Postman – for API testing and documentation

---

Procedure

Query Parameters

1. Filters

Filters should always be sent in Query Parameters and NEVER in the request body.

Filter Key

The filter key should be the same as the key returned in the Index endpoint.

Filter Format

Type	Format
Single filter	?filter[name]=value
Multiple filters	?filter[name1]=value1&filter[name2]=value2

Filter Types

String – Single value string:

?filter[name]=BE_sux

Value Array – Multiple values joined by commas:

?filter[merchant]=A,B,C

Number – Single or range values:

# Single value
?filter[amount][from]=120
?filter[amount][to]=120

# Both values (range)
?filter[amount][from]=120&filter[amount][to]=120

Date – Single or range values:

# Single value
?filter[created_at][from]=2020-12-18
?filter[created_at][to]=2020-12-18

# Both values (range)
?filter[created_at][from]=2020-12-18&filter[created_at][to]=2020-12-18

Complete Example

GET api/smart-plugin/transactions

Query params:

filter[terminal_id]: 77663808           // Single value
filter[created_at][from]: 2024-08-13    // Date range start
filter[created_at][to]: 2024-08-23      // Date range end
filter[branch_name]: BRGR,Wanted        // Value Array
filter[amount][from]: 1                 // Number range start
filter[amount][to]: 999                 // Number range end

---

2. Searching

Search Key

The search key should always be search.

Search Format

search=<search_term>

Example

GET api/smart-plugin/merchants?search=coffee

---

Selectors

Any resource that has a use case of being used as a filter or listed in a form input should have a selector endpoint provided.

Selector Response Shape

The selector's response should always follow this structure:

[
  {
    "key": "resource unique identifier",
    "text": "resource entry string value"
  }
]

Example: Branches Selector

Request:

GET api/v3/selector/branches

Response:

[
  {
    "key": "98e4f715-4ad8-4463-819a-d168892d95db",
    "text": "Branch 1"
  },
  {
    "key": "664d2659-edb8-4235-ad75-96d9be397768",
    "text": "Branch 2"
  },
  {
    "key": "d08db1f9-5d84-4d1f-9e62-435b7c3d3fc3",
    "text": "Branch 3"
  }
]

---

File Uploads

Any file upload should be handled in a separate common file upload endpoint provided by the BE team.

Upload Flow

1. Upload the file:

   • Request: POST with file in request body
   • Response: Uploaded file UUID and URL

2. Submit the file reference:

   • Use the uploaded file UUID in your main request

sequenceDiagram
    participant FE as Frontend
    participant Upload as Upload Endpoint
    participant API as Main API

    FE->>Upload: POST /upload (file)
    Upload-->>FE: { uuid, url }
    FE->>API: POST /resource (uuid)
    API-->>FE: Success

---

Anti-Patterns to Avoid

❌ Filter Array with Nested Indices

Problem: Filters listed as an array cause conflicts with nested value arrays.

// BAD - Don't do this
filters[0][value][0]=...

Solution: Use the filter format defined above.

---

❌ POST for GET Requests

Problem: Using POST method to fetch data violates HTTP conventions.

// BAD
POST /api/transactions
Body: { filters: {...} }

Solution: Use GET with query parameters.

// GOOD
GET /api/transactions?filter[status]=active

---

❌ Filters in Request Body

Problem: Sending filters in the request body instead of query parameters.

Solution: Always send filters in query parameters for GET requests.

---

❌ Inconsistent Filter Value Shapes

Problem: Filter values have no consistent shape (array, string, numbers mixed unpredictably).

Solution: Follow the filter types defined in this document.

---

Summary Table

Aspect	Correct Approach
Filter location	Query parameters, never request body
Filter key	Same as key returned in Index endpoint
Search key	Always search
Selector response	[{ key, text }] structure
File uploads	Separate upload endpoint, then use UUID
HTTP methods	GET for fetching, POST for creating

---

Change Log

Version	Date	Changes	Author
1.0.0	2024-11-13	Initial version	Mohamed Wagih

Approvers:

• Omar Atallah (2024-11-13)
• Mohamed Khalil (2024-11-13)

---

Related Documentation

• Development Environment Setup - Set up your development environment
• ACL Protection Rules - Access control implementation guidelines
• Welcome Guide - Onboarding guide for new team members
• Documentation Guidelines - How to contribute to documentation