Skip to main content
BitShift
Sign..In
Software Engineering

API Design Principles: Building APIs Developers Love

Practical API design guidelines covering naming conventions, error handling, pagination, and versioning for RESTful services.

Mbeah Essilfie

Mbeah Essilfie

June 25, 2026 at 06:03 AM

10 min read 2086 views
API Design Principles: Building APIs Developers Love

APIs Are User Interfaces

An API is a UI for developers. The same principles apply: consistency, discoverability, and helpful error messages.

Naming Conventions

✅ GET    /api/posts              — List posts
✅ GET    /api/posts/:id          — Get a post
✅ POST   /api/posts              — Create a post
✅ PATCH  /api/posts/:id          — Update a post
✅ DELETE /api/posts/:id          — Delete a post

❌ GET    /api/getPost/:id        — Don't use verbs in URLs
❌ POST   /api/posts/create       — The HTTP method IS the verb
❌ GET    /api/post/:id           — Use plural nouns

Consistent Response Envelope

// Success response
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Must be a valid email" }
    ]
  }
}

Pagination

// Offset-based (simple, supports jumping to pages)
GET /api/posts?page=2&limit=20

// Cursor-based (better performance at scale)
GET /api/posts?cursor=abc123&limit=20
Use offset pagination for admin dashboards where users jump to specific pages. Use cursor pagination for infinite scroll feeds where performance matters.

Filtering and Sorting

GET /api/posts?status=published&sort=-publishedAt&tags=vue,nuxt

Convention: prefix with - for descending sort.

Error Handling

Return appropriate HTTP status codes:

// server/utils/errors.ts
export function notFound(resource: string) {
  throw createError({
    statusCode: 404,
    message: `${resource} not found`,
    data: { code: 'NOT_FOUND' },
  })
}

export function validationError(errors: ValidationError[]) {
  throw createError({
    statusCode: 422,
    message: 'Validation failed',
    data: { code: 'VALIDATION_ERROR', details: errors },
  })
}

Versioning Strategy

For most APIs, URL versioning is simplest:

/api/v1/posts
/api/v2/posts

But consider: do you actually need versioning? For internal APIs (your own frontend), evolve the API in place and update both sides together.

Rate Limiting Headers

Always communicate limits:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1625097600

Summary

Good API design is: consistent naming, predictable responses, helpful errors, and clear documentation. Make it obvious, then make it fast.

Node.jsAPI DesignArchitecture
Mbeah Essilfie

Written by Mbeah Essilfie

Fullstack Software Developer

Read next

The Complete Guide to Vue 3 Composables
12 min read

The Complete Guide to Vue 3 Composables

Understand the power of Vue 3's Composition API through practical, real-world composable patterns that you can use today.

Mbeah EssilfieMbeah Essilfie
981