Daanbi Services
Technical Documentation

API Development Standards

Comprehensive guidelines for designing, developing, and maintaining enterprise-grade APIs following industry best practices and security standards

Version: 2.1.0
Updated: January 2025
Status: Active

Quick Navigation

Core Standards

Security & Authentication

Implementation

RESTful Design Principles

Core REST Principles

1. Resource-Based Architecture

APIs should be organized around resources (nouns) rather than actions (verbs). Each resource should have a unique identifier and support standard operations.

✓ Good Examples:
/users
/users/{id}
/users/{id}/orders
✗ Bad Examples:
/getUsers
/createUser
/deleteUserById

2. Stateless Communication

Each request must contain all information necessary to process it. Server should not store client context between requests.

Key Requirements:
  • • Include authentication tokens in headers
  • • Pass all required parameters in request
  • • No server-side session storage
  • • Client manages application state

Uniform Interface Constraints

Resource Identification

Resources are identified by URLs and remain stable over time

/api/v1/users/12345

Resource Manipulation

Use HTTP methods to manipulate resources through representations

GET, POST, PUT, DELETE

Self-Descriptive Messages

Include metadata to describe how to process the message

Content-Type, Cache-Control

URL Naming Conventions

Standard URL Structure

https://api.example.com/v1/resources/{id}/subresources?parameter=value
├── Base URL: https://api.example.com
├── Version: /v1
├── Resource: /resources
├── Identifier: /{id}
├── Sub-resource: /subresources
└── Query Parameters: ?parameter=value

Naming Rules

  • Use lowercase letters only
  • Separate words with hyphens (kebab-case)
  • Use plural nouns for collections
  • Keep URLs intuitive and hierarchical

Examples

/users
/user-profiles
/orders/{orderId}/items
/customers/{id}/billing-addresses

Resource Relationship Patterns

Pattern URL Structure Use Case
Collection /users List all users
Individual Resource /users/{id} Specific user
Sub-collection /users/{id}/orders Orders for a user
Sub-resource /users/{id}/profile User's profile (1:1 relationship)

HTTP Methods & Status Codes

Standard HTTP Methods

GET

Retrieve Resources

Retrieves data without modifying server state. Must be safe and idempotent.

GET /users → List all users
GET /users/123 → Get specific user
GET /users/123/orders → Get user's orders
Query Parameters:
?limit=20&offset=0
?sort=created_at&order=desc
?filter=status:active
POST

Create Resources

Creates new resources. Not idempotent - multiple calls create multiple resources.

POST /users → Create new user
POST /users/123/orders → Create order for user
Request Example:
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "customer"
}
PUT

Update/Replace Resources

Replaces entire resource. Idempotent - multiple calls have same effect.

PUT /users/123 → Update entire user
PUT /users/123/profile → Replace profile
PATCH Alternative:

Use PATCH for partial updates to avoid overwriting entire resource.

DELETE

Remove Resources

Removes resources from server. Idempotent after first successful deletion.

DELETE /users/123 → Delete user
DELETE /users/123/orders/456 → Delete specific order
Soft Delete Option:

Consider marking as deleted instead of permanent removal for audit trails.

HTTP Status Codes

Success Codes (2xx)

200 OK - Request successful
201 Created - Resource created
204 No Content - Success, no response body

Redirection Codes (3xx)

301 Moved Permanently
304 Not Modified

Client Error Codes (4xx)

400 Bad Request - Invalid syntax
401 Unauthorized - Authentication required
403 Forbidden - Access denied
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limited

Server Error Codes (5xx)

500 Internal Server Error
503 Service Unavailable

Authentication & Authorization

Authentication Methods

JWT (JSON Web Tokens)

Recommended for most APIs. Stateless, secure, and includes claims about the user.

# Authorization Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
JWT Claims:
  • • sub: Subject (user ID)
  • • iat: Issued at timestamp
  • • exp: Expiration timestamp
  • • aud: Audience (API identifier)
  • • Custom claims: roles, permissions

API Keys

Suitable for service-to-service communication and public APIs with rate limiting.

# Header-based API Key
X-API-Key: abc123def456ghi789
# Query Parameter (less secure)
GET /users?api_key=abc123def456
Best Practices:
  • • Use HTTPS only
  • • Implement rate limiting
  • • Rotate keys regularly
  • • Never log API keys

Authorization Models

Role-Based Access Control (RBAC)

Users are assigned roles, and roles have specific permissions.

admin → all permissions
editor → read, write
viewer → read only
{
  "user_id": "123",
  "roles": ["editor"],
  "permissions": [
    "users:read",
    "users:write",
    "orders:read"
  ]
}

Attribute-Based Access Control (ABAC)

Fine-grained access control based on user attributes, resource properties, and environmental factors.

Example Policy: Allow if user.department == "HR" AND resource.type == "employee_record" AND time.hour BETWEEN 9 AND 17

API Versioning Strategy

Versioning Methods

Recommended

URL Path Versioning

Include version number directly in the URL path. Clear, explicit, and easy to implement.

https://api.example.com/v1/users
https://api.example.com/v2/users
https://api.example.com/v3/users
Benefits:
  • • Highly visible and explicit
  • • Easy to implement and test
  • • Supports different documentation per version
  • • Clear separation of concerns

Header-Based Versioning

Use custom headers to specify API version. Keeps URLs clean but less discoverable.

X-API-Version: 2.1
Accept: application/vnd.api.v2+json
Use Cases:
  • • When URLs must remain stable
  • • For content negotiation
  • • Internal APIs with controlled clients

Version Lifecycle Management

Active Version

Current production version with full support and active development.

  • • Bug fixes and security patches
  • • New features and enhancements
  • • Full documentation and support

Deprecated Version

Legacy version marked for retirement. Critical fixes only.

  • • Security patches only
  • • No new features
  • • Migration guides provided
  • • Sunset date announced

Retired Version

Version no longer supported. Returns deprecation warnings.

  • • No support or updates
  • • May return HTTP 410 Gone
  • • Documentation archived

Need Help Implementing These Standards?

Our API development team specializes in building enterprise-grade APIs that follow industry best practices and security standards. Get expert guidance for your API project.

Consult Our API Experts More Documentation