API Design and Microservice Architecture: Building Scalable Systems in 2026

In modern software development, APIs are the universal language that allows applications to talk to each other. As IPEC Labs, we have developed an API infrastructure on the NŞEFİM restaurant management platform that processes thousands of API calls per day, manages real-time WebSocket connections and integrates with four different food platforms. In this article, we share proven API design principles and microservice architecture experiences in the production environment.

Golden Rules of RESTful API Design

Good API design centers around developer experience (DX). Developers using your API,whether someone on your team or a third-party integrator,should be able to work with minimal reference to documentation.

The first and most important rule is consistency. URL structure, HTTP method usage, error format and pagination approach should be consistent across the API. In our NŞEFİM API, all endpoints follow the same patterns. Collection endpoints use plural names (orders, products, branches), singular resource access is done with ID, and filtering is done with query parameters.

The second rule is to use the correct HTTP method. GET is used only for reading data, POST is used to create a new record, PUT/PATCH is used to update the existing record, and DELETE is used to delete it. Order status update in NŞEFİM is done with PATCH, because we only update the status field, not the entire order.

The third rule is meaningful HTTP status codes. 200 successful reads, 201 successful creations, 400 invalid requests, 401 authentication errors, 403 authorization errors, 404 resources not found, 429 rate limit exceeded, 500 server errors. Each status code allows the client to handle the error programmatically.

Microservices Architecture: When and Why?

Monolithic architecture is ideal for getting started simple and fast. However, as the application grows, the team expands, and different components have different scaling needs, microservices become inevitable.

NŞEFİM platform initially had a monolithic structure. However, as the order volume increased and platform integrations increased, the transition to microservice architecture became necessary. Today NŞEFİM consists of five main services.

The first is the API Gateway service, the entry point for all requests, responsible for authentication, rate limiting and routing. The second is Order Service, manages order creation, updating and tracking. Third, Kitchen Display Service, provides real-time order delivery and readiness tracking to kitchen screens. Fourth, Integration Service, manages communication with Yemeksepeti, Getir, Trendyol and Migros APIs. Fifth, Finance Service, performs income-expense tracking, cash reports and consolidated financial calculations.

Each service can be deployed, scaled and updated independently. During meal times, the ordering service scales automatically, while the financial service continues to operate at constant capacity.

WebSocket: The Heart of Real-Time Communication

One of the most critical features of NŞEFİM is that orders appear instantly on the kitchen screen. This isn’t possible with HTTP’s request-response model, with WebSocket, bi-directional communication is required over an always-on connection.

WebSocket connection management presents serious challenges in a production environment. Connection drops are inevitable, network outages, server reboots, or client-side issues can break the connection. Therefore, an automatic reconnection mechanism (with exponential backoff) is critical. When the connection is lost in NCHEFIM, the client tries to reconnect at increasing intervals of 1 second, then 2 seconds, then 4 seconds. The interval is fixed when the maximum 30 seconds is reached.

The heartbeat mechanism is used to verify the liveness of the connection. Every 30 seconds the server sends a “ping”, the client responds with a “pong”. If no pong is received for 90 seconds, the connection is considered broken and resources are released.

Message sequencing and delivery guarantee are also important. It is vital that orders arrive on the kitchen screen in the correct order and completely. A sequence number is assigned to each message, and the client can detect missing messages and request them again from the server.

API Security

API security is one of IPEC Labs’ primary focus areas. Our security strategy is multi-layered.

We use JWT (JSON Web Token) based authentication. Access tokens are short-lived (15 minutes), refresh tokens are longer (7 days). Tokens are stored in HttpOnly cookies, inaccessible via JavaScript, protected against XSS attacks.

We prevent abuse with rate limiting. The maximum number of requests per minute is determined for each API endpoint. In NŞEFİM, the login endpoint is limited to 10 requests per minute, effectively preventing brute force attacks. The order listing endpoint is limited to 100 requests per minute.

Input validation is the first line of ensuring that all incoming data is secure. All inputs are sanitized against SQL injection, XSS and other injection attacks. Runtime validation is implemented at the TypeScript level with the Zod library.

CORS policies ensure that only requests from authorized domains are accepted. NŞEFIM API only accepts requests from nsefim.com and app.nsefim.com domains.

Platform Integrations: Real World Challenges

NŞEFİM’s Yemeksepeti, Getir, Trendyol and Migros integrations are an excellent case study showing the real-world challenges of API design.

Each platform uses different API standards. One uses REST while the other is webhook based. The data formats are different, one can send JSON, the other can send XML. Error codes are not standardized. Rate limit policies vary.

We used Adapter Pattern to manage this complexity. A separate adapter module was written for each platform. Adapter converts platform-specific data into NŞEFİM’s standard data model. The main business logic is completely unaware of platform details, it just works with the standard order object.

We ensured resilience to platform failures with the Circuit Breaker pattern. If a platform API becomes unresponsive, the circuit breaker kicks in and does not send requests to that platform for a certain period of time. This prevents cascade failures and ensures that the rest of the system continues to function properly.

Database Access Layer

The layer between the API and the database is critical for performance and security. At IPEC Labs, we use Prisma as ORM (Object-Relational Mapping).

Prisma’s type safety, combined with TypeScript, provides compile-time error detection in database queries. If you use the wrong table name or column name, the application won’t even compile. This dramatically reduces runtime errors.

The N+1 query problem is one of the most common performance pitfalls of using ORM. When pulling the order list in NŞEFİM, instead of querying the products of each order separately, we pull all related data in a single query with Prisma’s include feature.

Connection pooling ensures efficient use of database connections. Instead of opening a new connection for each request, existing connections from a connection pool are used and returned to the pool when the transaction is finished.

Documentation and Developer Experience

The best API is the best documented API. NŞEFİM API is documented with the OpenAPI 3.0 specification. Interactive documentation is available with Swagger UI, developers can make API calls directly from the browser.

Request and response examples, error scenarios and rate limit information are documented for each endpoint. It can be exported as a Postman collection and used for automatic SDK generation.

Conclusion

API design and microservices architecture are the cornerstones of modern software engineering. A properly designed API extends the life of your application, increases your team’s productivity, and reduces integration costs.

As IPEC Labs, we apply these principles in all our products, from NŞEFİM to NZeca, from Smart School to corporate projects. Our APIs provide solid foundations on which our customers and partners can integrate with confidence.