We design API-first systems that prioritize developer experience, performance, and long-term maintainability. Our approach covers REST, GraphQL, microservices, and event-driven architectures.

API Patterns We Use

1. RESTful APIs

Our default choice for most projects — battle-tested, well-understood, and easy to cache.

When we use REST:

• CRUD operations and resource-based APIs
• Public-facing APIs that need broad compatibility
• Projects where simplicity and HTTP caching matter

Request flow:

Key practices:

• Resource naming: /users, /projects/{id}, /orders/{orderId}/items
• HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
• Status codes: 200 (OK), 201 (Created), 400 (Bad Request), 404 (Not Found), 500 (Server Error)
• Versioning: /v1/users, /v2/users or Accept: application/vnd.api+json; version=1
• Pagination: Cursor-based or offset-based with ?page=2&limit=20

// Example: NestJS REST Controller
@Controller('v1/projects')
export class ProjectsController {
  @Get()
  async findAll(@Query() query: PaginationDto) {
    return this.projectsService.findAll(query);
  }

  @Get(':id')
  async findOne(@Param('id') id: string) {
    return this.projectsService.findOne(id);
  }

  @Post()
  async create(@Body() dto: CreateProjectDto) {
    return this.projectsService.create(dto);
  }
}

2. GraphQL

For complex data requirements, mobile apps, and real-time updates.

When we use GraphQL:

• Clients need to fetch nested, related data in one request
• Mobile apps want to minimize over-fetching
• Real-time features (subscriptions)

GraphQL flow (single request, flexible response):

Key practices:

• Type-safe schemas: All queries and mutations are strongly typed
• N+1 query prevention: DataLoader for batch fetching
• Field-level auth: Granular permissions on resolvers
• Subscriptions: WebSocket-based real-time updates

// Example: GraphQL Schema (Code-First with NestJS)
@ObjectType()
export class Project {
  @Field(() => ID)
  id: string;

  @Field()
  name: string;

  @Field(() => [Task])
  tasks: Task[];
}

@Resolver(() => Project)
export class ProjectResolver {
  @Query(() => [Project])
  async projects() {
    return this.projectService.findAll();
  }

  @ResolveField(() => [Task])
  async tasks(@Parent() project: Project) {
    return this.taskService.findByProjectId(project.id);
  }
}

3. Microservices

For large, complex systems that need independent scaling and deployment.

When we use microservices:

• Multiple teams working on different features
• Parts of the system have different scaling needs
• We need polyglot architecture (different services in different languages)

Key practices:

• Service boundaries: Each service owns its data and domain logic
• Communication: REST, gRPC, or message queues
• Service discovery: Kubernetes DNS, Consul, or AWS Service Discovery
• API Gateway: Single entry point for clients (Kong, AWS API Gateway, Traefik)
• Circuit breakers: Resilience patterns (timeouts, retries, fallbacks)

Architecture example:

4. Event-Driven Architecture

For asynchronous workflows and loosely coupled systems.

When we use events:

• Background jobs (email sending, PDF generation)
• Workflows that span multiple services
• Audit logs and analytics

Event-driven flow:

Key practices:

• Message brokers: RabbitMQ, AWS SQS, Kafka
• Event schemas: Versioned, documented event payloads
• Idempotency: Events can be processed multiple times safely
• Dead letter queues: Failed messages are retried or moved to DLQ

// Example: Event Emitter Pattern
@Injectable()
export class OrderService {
  constructor(private eventBus: EventBus) {}

  async createOrder(dto: CreateOrderDto) {
    const order = await this.orderRepository.create(dto);
    
    // Emit event for other services to react
    await this.eventBus.publish(new OrderCreatedEvent(order));
    
    return order;
  }
}

// Another service listens to this event
@EventsHandler(OrderCreatedEvent)
export class SendOrderConfirmationHandler {
  async handle(event: OrderCreatedEvent) {
    await this.emailService.sendOrderConfirmation(event.order);
  }
}

API Design Best Practices

Explore More