# Backend API Restful Design

> REST principles, resource naming, HTTP methods.

- Skill: `valec3/backend-api-restful-design` (Agent Skill)
- Install (CLI): `npx skillmds add valec3/backend-api-restful-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valec3/backend-api-restful-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: valec3 (https://skillmd.com/u/valec3)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/valec3/backend-api-restful-design

---


# Backend API RESTful Design

## When to use this skill
- Designing APIs
- Creating endpoints
- Following REST standards
- API consistency

## Workflow
- [ ] Use nouns for resources
- [ ] Use HTTP methods correctly
- [ ] Return proper status codes
- [ ] Version APIs
- [ ] Use plural nouns

## Instructions

### REST Principles
```
GET    /api/users      - List users
GET    /api/users/1    - Get user
POST   /api/users      - Create user
PUT    /api/users/1    - Update user
PATCH  /api/users/1    - Partial update
DELETE /api/users/1    - Delete user
```

### Nested Resources
```
GET    /api/users/1/orders        - User's orders
POST   /api/users/1/orders        - Create order for user
GET    /api/orders/123            - Single order (flat)
```

### Status Codes
```php
<?php

return $this->respond($data, 200);        // OK
return $this->respondCreated($data);      // 201
return $this->respondNoContent();         // 204
return $this->failValidationErrors($e);   // 400
return $this->failUnauthorized();         // 401
return $this->failForbidden();            // 403
return $this->failNotFound();             // 404
return $this->failServerError($message);  // 500
```

## Resources
- Use nouns, not verbs
- HTTP methods for actions
- Proper status codes