API Development Company: REST, GraphQL & gRPC — The Complete Guide

By Viprasol Tech Team

---

APIs are the connective tissue of modern software. Whether you're building a mobile application that needs a backend, integrating with third-party services, exposing your product to enterprise customers, or enabling a developer ecosystem, API design quality directly determines how fast the teams consuming the API can move.

A well-designed API is stable, predictable, and forgiving of client errors. A poorly designed one is a source of perpetual debugging, integration failures, and support tickets. The difference between them is not luck — it's the product of deliberate design decisions made before writing the first endpoint.

---

Protocol Selection: REST vs. GraphQL vs. gRPC

The most consequential early API decision:

REST (HTTP + JSON) — the universal standard. Every HTTP client in every language can call a REST API without additional tooling. Caching is built into HTTP. The ecosystem (OpenAPI, Swagger, Postman, API gateways) is mature. Choose REST when your API will be consumed by third parties, mobile apps, or web clients.

GraphQL — a query language for APIs. Clients specify exactly what data they need; the API returns exactly that. Solves the over-fetching problem (REST often returns more data than the client needs) and under-fetching (REST often requires multiple requests for related data). Choose GraphQL when the primary consumer is a frontend you control with complex, variable data requirements.

gRPC — Protocol Buffers over HTTP/2. Binary protocol, significantly faster than JSON, bidirectional streaming, strongly typed contracts. Choose gRPC for internal service-to-service communication, especially when latency and throughput matter (microservices architecture, real-time data).

---

REST API Design: Production Standards

URL Structure

GET    /v1/projects                  — list projects
POST   /v1/projects                  — create project
GET    /v1/projects/{id}             — get project
PATCH  /v1/projects/{id}             — partial update
DELETE /v1/projects/{id}             — delete project
GET    /v1/projects/{id}/members     — list members (nested resource)
POST   /v1/projects/{id}/members     — add member

Rules:

• Nouns, not verbs (never /getProject or /createProject)
• Plural resource names (/projects, not /project)
• HTTP method conveys the action
• PATCH for partial update, PUT for full replacement
• Nested resources for clear ownership (project members belong to a project)

Request Validation and Error Responses

// Zod schema for request validation (TypeScript)
import { z } from 'zod';

const CreateProjectSchema = z.object({
  name:        z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  visibility:  z.enum(['private', 'team', 'public']).default('private'),
  tags:        z.array(z.string().max(50)).max(10).optional(),
});

// Standardized error response format
interface APIError {
  error: {
    code:    string;     // machine-readable: "VALIDATION_ERROR", "NOT_FOUND"
    message: string;     // human-readable
    details?: Record<string, string[]>;  // field-level errors
    requestId: string;   // for debugging
  };
}

// Express error handler
app.post('/v1/projects', async (req, res) => {
  const parsed = CreateProjectSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({
      error: {
        code:      'VALIDATION_ERROR',
        message:   'Request body validation failed',
        details:   parsed.error.flatten().fieldErrors,
        requestId: req.id,
      }
    });
  }
  // ... proceed with validated data
});

Pagination

// Cursor-based pagination (better than offset for large datasets)
interface PaginatedResponse<T> {
  data:       T[];
  pagination: {
    hasNextPage: boolean;
    nextCursor:  string | null;  // opaque cursor for the next page
    total?:      number;         // optional — expensive to compute at scale
  };
}

async function listProjects(params: {
  cursor?: string;
  limit?:  number;
  filter?: { status?: string };
}): Promise<PaginatedResponse<Project>> {
  const limit = Math.min(params.limit ?? 20, 100);

  const where = {
    ...(params.cursor ? { id: { lt: decodeCursor(params.cursor) } } : {}),
    ...(params.filter?.status ? { status: params.filter.status } : {}),
  };

  const projects = await db.project.findMany({
    where,
    take:    limit + 1,  // fetch one extra to determine hasNextPage
    orderBy: { id: 'desc' },
  });

  const hasNextPage = projects.length > limit;
  const data = projects.slice(0, limit);

  return {
    data,
    pagination: {
      hasNextPage,
      nextCursor: hasNextPage ? encodeCursor(data[data.length - 1].id) : null,
    },
  };
}

---

Authentication Patterns

JWT Bearer tokens — the standard for API authentication. Short-lived access tokens (15 minutes), long-lived refresh tokens (7–30 days). Refresh token rotation on each use prevents replay attacks.

API Keys — for developer/machine-to-machine access. Store hashed in database (bcrypt or SHA-256 with salt); show the key once at creation; allow multiple keys per account for rotation.

// API key creation and validation
import { createHash, randomBytes } from 'crypto';

async function createAPIKey(accountId: string, label: string) {
  const rawKey    = `vsp_${randomBytes(32).toString('hex')}`;
  const keyHash   = createHash('sha256').update(rawKey).digest('hex');
  const keyPrefix = rawKey.substring(0, 12);  // for identification

  await db.apiKey.create({
    data: { accountId, label, keyHash, keyPrefix }
  });

  return rawKey;  // only time the full key is returned — save it now
}

async function validateAPIKey(rawKey: string): Promise<APIKey | null> {
  const keyHash = createHash('sha256').update(rawKey).digest('hex');
  return db.apiKey.findUnique({
    where: { keyHash, revokedAt: null }
  });
}

---

Rate Limiting

// Sliding window rate limiter using Redis
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

async function checkRateLimit(
  key: string,                // e.g., "api_key:abc123" or "ip:1.2.3.4"
  limit: number,              // max requests
  windowSeconds: number,      // per window
): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
  const now    = Date.now();
  const window = Math.floor(now / (windowSeconds * 1000));
  const redisKey = `ratelimit:${key}:${window}`;

  const count = await redis.incr(redisKey);
  if (count === 1) {
    await redis.expire(redisKey, windowSeconds * 2);
  }

  return {
    allowed:   count <= limit,
    remaining: Math.max(0, limit - count),
    resetAt:   (window + 1) * windowSeconds * 1000,
  };
}

// Middleware
app.use(async (req, res, next) => {
  const key = req.apiKey?.id ?? `ip:${req.ip}`;
  const limit = req.apiKey ? 1000 : 60;  // authenticated vs anonymous

  const result = await checkRateLimit(key, limit, 60);

  res.setHeader('X-RateLimit-Limit',     limit);
  res.setHeader('X-RateLimit-Remaining', result.remaining);
  res.setHeader('X-RateLimit-Reset',     Math.floor(result.resetAt / 1000));

  if (!result.allowed) {
    return res.status(429).json({
      error: { code: 'RATE_LIMIT_EXCEEDED', message: 'Too many requests' }
    });
  }
  next();
});

---

API Versioning Strategy

URL versioning (/v1/, /v2/) — explicit, cacheable, easy to route. The standard for public APIs. Maintain backward compatibility within a version; deprecate and sunset old versions with adequate notice (minimum 12 months).

Deprecation headers:

res.setHeader('Deprecation', 'Sun, 01 Dec 2024 00:00:00 GMT');
res.setHeader('Sunset',      'Sun, 01 Jun 2025 00:00:00 GMT');
res.setHeader('Link',        '<https://docs.api.com/v2/projects>; rel="successor-version"');

---

OpenAPI Documentation

A public API without accurate documentation is unusable. OpenAPI (formerly Swagger) is the standard:

# openapi.yaml excerpt
openapi: 3.1.0
info:
  title: Viprasol Platform API
  version: 1.0.0

paths:
  /v1/projects:
    post:
      summary: Create a project
      tags: [Projects]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateProjectRequest' }
      responses:
        '201': { description: Project created, content: { application/json: { schema: { $ref: '#/components/schemas/Project' } } } }
        '400': { description: Validation error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
        '401': { description: Unauthorized }

Generate documentation from code (NestJS Swagger, FastAPI automatic docs) rather than maintaining it separately — they drift apart immediately.

---

API Development Cost Ranges

---

Working With Viprasol

We design and build APIs used by mobile applications, third-party integrators, and internal microservices. Our APIs are OpenAPI-documented from day one, rate-limited, versioned, and monitored.

Our web and API development services cover REST, GraphQL, and internal gRPC service design.

Building an API? Viprasol Tech designs and develops APIs for startups and enterprises. Contact us.

---

See also: Node.js Development Company · Custom Web Application Development · SaaS Development Services

Sources: OpenAPI Specification 3.1 · GraphQL Specification · gRPC Documentation