Back to API development

API development

Styles & technology

Choosing the right API style for each consumer, and the technology stack to build it on

API styles & protocols

There is no single best API style. The right choice depends on who calls the API, how much data they need and how fast it has to arrive.

One question, five API styles

“Show customer 1042 with their three latest orders.”

ClientJSONAPI

  1. GET /customers/1042

  2. 200 OK · customer1.2 KB

  3. GET /customers/1042/orders?limit=3

  4. 200 OK · 3 orders3.4 KB

Round trips 2

Payload
0.0 KB

Illustrative example

The same data costs a different number of round trips and bytes in every style. Picking the style per consumer keeps apps fast and integrations lean.

RESTful APIs

Representational State Transfer (REST) is the most widely adopted API architectural style. REST APIs use standard HTTP methods and are stateless, cacheable, and scalable. Learn more about API design best practices.

  • Resources & URIs: Noun-based resource naming (e.g., /customers, /orders)
  • HTTP methods: GET, POST, PUT, PATCH, DELETE for CRUD operations
  • Status codes: Proper use of 2xx, 4xx, 5xx response codes
  • HATEOAS: Hypermedia links for discoverability

GraphQL

Query language for APIs that gives clients control over the data they receive. Ideal for complex data requirements and mobile applications.

  • Flexible queries: Clients specify exactly what data they need
  • Single endpoint: One endpoint for all operations
  • Strongly typed: Schema-first development with type safety
  • Real-time: Built-in support for subscriptions and live updates

gRPC

High-performance RPC framework using HTTP/2 and protocol buffers. Ideal for microservices communication. Learn about gRPC in ASP.NET Core.

  • Binary protocol: Faster and more compact than JSON
  • Streaming: Client, server, and bi-directional streaming
  • Code generation: Auto-generate client and server code from .proto files
  • Language agnostic: Support for multiple programming languages

WebSockets & SignalR

Real-time, bi-directional communication for live updates. SignalR simplifies real-time web functionality.

  • Persistent connections: Long-lived connections for instant updates
  • Push notifications: Server-initiated messages to clients
  • Use cases: Chat, dashboards, gaming, collaborative editing
  • Fallback support: Automatic fallback to Server-Sent Events, then long polling, if WebSockets are unavailable

OData

Open Data Protocol for queryable RESTful APIs. Widely used in Microsoft ecosystems (Dynamics 365, SharePoint).

  • Query language: URL-based filtering, sorting, paging, expansion
  • Metadata: Self-describing APIs with $metadata endpoint
  • Batch operations: Submit multiple operations in single request
  • Delta queries: Retrieve only changed data since last query

API development technologies

I default to the Microsoft stack and choose other runtimes where the team or the workload calls for them.

ASP.NET Core Web API

Modern, cross-platform framework for building HTTP services. Learn more about ASP.NET Core Web API.

Key features

  • Minimal APIs: Simplified syntax for small microservices
  • Controllers: Full-featured MVC pattern for complex APIs
  • Model binding: Automatic parameter binding from routes, query strings, body
  • Validation: Data annotations and FluentValidation support
  • Dependency injection: Built-in DI container
  • Middleware pipeline: Extensible request processing pipeline

OpenAPI (Swagger) integration

Generate OpenAPI documents with the built-in Microsoft.AspNetCore.OpenApi package (.NET 9 and later) or Swashbuckle:

  • Interactive API documentation (Swagger UI)
  • Client SDK generation for multiple languages
  • API versioning support
  • XML comments for detailed operation descriptions

Azure Functions (serverless APIs)

Event-driven, serverless compute for HTTP-triggered APIs. Learn about Azure Functions.

When to use Azure Functions

  • Event-driven workloads: Process queue messages, blob uploads, database changes
  • Scheduled tasks: Cron-based background jobs
  • Lightweight APIs: Simple HTTP endpoints without complex routing
  • Cost optimization: Pay only for execution time (consumption plan)
  • Auto-scaling: Automatic horizontal scaling based on load

Node.js (Express, NestJS, Fastify)

  • Express: Minimalist, flexible framework for quick API development
  • NestJS: TypeScript-first, enterprise-grade framework with Angular-like architecture
  • Fastify: High-performance framework focused on speed and low overhead

Python (FastAPI, Django REST Framework)

  • FastAPI: Modern, async framework with automatic OpenAPI generation
  • Django REST Framework: Powerful toolkit for building web APIs with Django
NextDesign principles

Ready to build reliable, well-documented APIs?

Let's discuss how well-designed APIs can power your digital ecosystem with secure, scalable, and developer-friendly services.