REST API Design Prompt for Clean Endpoints
A structured prompt that designs resource-oriented endpoints with verbs, status codes, and pagination decided — with a real example spec.
Enhanced prompt — ready to use
ROLE You are a senior backend developer with expertise in designing RESTful APIs. Your goal is to create a comprehensive and efficient REST API design tailored to the requirements of a specific application. TASK Design a RESTful API for the given app, detailing the necessary endpoints, HTTP methods, request and response formats, authentication methods, and error handling. Think through this step by step, considering best practices for API design, scalability, security, and usability. CONTEXT The user requests a REST API design for their application. Assume the app is a typical modern web or mobile application that requires CRUD operations and secure data handling. The intended audience includes backend developers who will implement and maintain the API. REQUIREMENTS - Define clear and logically structured API endpoints aligned with resource-based design principles. - Specify HTTP methods for each endpoint (GET, POST, PUT, DELETE, etc.). - Include examples of request and response payloads in JSON format. - Outline authentication and authorization mechanisms (e.g., OAuth, JWT). - Address error handling with appropriate HTTP status codes and error message formats. - Follow best practices for REST API design, including statelessness and proper use of status codes. - Think step by step and consider edge cases such as invalid inputs and security threats. - Before finalizing, verify your answer for correctness, completeness, and adherence to REST conventions. OUTPUT FORMAT Present the API design using organized sections: 1. Overview of the API and its purpose. 2. List of endpoints with HTTP methods. 3. Detailed request and response schemas for each endpoint. 4. Authentication and authorization strategy. 5. Error handling approach and sample error responses. Use bullet points, numbered lists, and code blocks with JSON examples as needed.
That's what PromptAI produced from this vague prompt: “design a rest api for my app”
Example result
Certainly! Below is a step-by-step comprehensive RESTful API design for a generic modern web/mobile application supporting CRUD operations and secure data handling.
---
## 1. Overview of the API and Its Purpose
- **Purpose:**
Provide a secure, scalable, and well-structured RESTful API enabling clients to perform CRUD operations on application resources (e.g., users, items, orders, etc.).
- **Key considerations:**
- Resource-driven URIs following REST principles.
- Stateless requests with JWT-based authentication.
- JSON as the primary data interchange format.
- Proper HTTP status codes for response clarity.
- Input validation and error reporting.
- Scalability and security-aware design (e.g., rate limiting can be added later at infra level).
---
## 2. List of Endpoints with HTTP Methods
Assuming a sample app with two main resources: `users` and `items`.
| Endpoint | HTTP Method | Description |
| -------------------------- | ----------- | ---------------------------------- |
| `/auth/register` | POST | Register new user |
| `/auth/login` | POST | Authenticate user (login) |
| `/auth/refresh-token` | POST | Refresh access token |
| `/users` | GET | List all users (admin only) |
| `/users/{userId}` | GET | Get user details by ID |
| `/users/{userId}` | PUT | Update user info |
| `/users/{userId}` | DELETE | Delete user |
| `/items` | GET | List all items |
| `/items` | POST | Create a new item |
| `/items/{itemId}` | GET | Get item details |
| `/items/{itemId}` | PUT | Update item details |
| `/items/{itemId}` | DELETE | Delete item |
---
## 3. Detailed Request and Response Schemas
### 3.1 Authentication Endpoints
#### 3.1.1 POST `/auth/register`
- **Request:**
```json
{
"username": "johndoe",
"email": "john@example.com",
"password": "s3cureP@ssword"
}
```
- **Response (201 Created):**
```json
{
"id": "user_12345",
"username": "johndoe",
"email": "john@example.com",
"createdAt": "2024-06-01T12:00:00Z"
}
```
---
#### 3.1.2 POST `/auth/login`
- **Request:**
```json
{
"username": "johndoe",
"password": "s3cureP@ssword"
}
```
- **Response (200 OK):**
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "dGhpcy1pcy1hLXJlZnJlc2gtdG9rZW4...",
"expiresIn": 3600
}
```
---
#### 3.1.3 POST `/auth/refresh-token`
- **Request:**
```json
{
"refreshToken": "dGhpcy1pcy1hLXJlZnJlc2gtdG9rZW4..."
}
```
- **Response (200 OK):**
```json
{
"accessToken": "new-access-token",
"expiresIn": 3600
}
```
---
### 3.2 Users Endpoints
**Note:** User `id` is a string (UUID or similar).
#### 3.2.1 GET `/users`
- **Description:** Lists all users; admin-only access.
- **Response (200 OK):**
```json
[
{
"id": "user_12345",
"username": "johndoe",
"email": "john@example.com",
"role": "user",
"createdAt": "2024-06-01T12:00:00Z"
},
{
"id": "user_67890",
"username": "janedoe",
"email": "jane@example.com",
"role": "admin",
"createdAt": "2024-06-02T08:30:00Z"
}
]
```
---
#### 3.2.2 GET `/users/{userId}`
- **Response (200 OK):**
```json
{
"id": "user_12345",
"username": "johndoe",
"email": "john@example.com",
"role": "user",
"createdAt": "2024-06-01T12:00:00Z"
}
```
---
#### 3.2.3 PUT `/users/{userId}`
- **Request:** (example updating email and username)
```json
{
"username": "john_updated",
"email": "john_upd@example.com"
}
```
- **Response (200 OK):**
```json
{
"id": "user_12345",
"username": "john_updated",
"email": "john_upd@example.com",
"role": "user",
"updatedAt": "2024-06-03T15:45:00Z"
}
```
---
#### 3.2.4 DELETE `/users/{userId}`
- **Description:** Delete user account.
- **Response (204 No Content):** No body.
---
### 3.3 Items Endpoints
#### 3.3.1 GET `/items`
- **Response (200 OK):**
```json
[
{
"id": "item_abc123",
"name": "Sample Item",
"description": "This is a sample item.",
"price": 19.99,
"createdAt": "2024-06-01T10:00:00Z"
},
{
"id": "item_def456",
"name": "Another Item",
"description": "Another item description.",
"price": 29.99,
"createdAt": "2024-06-02T09:30:00Z"
}
]
```
---
#### 3.3.2 POST `/items`
- **Request:**
```json
{
"name": "New Item",
"description": "Description of the item",
"price": 15.5
}
```
- **Response (201 Created):**
```json
{
"id": "item_xyz789",
"name": "New Item",
"description": "Description of the item",
"price": 15.5,
"createdAt": "2024-06-03T11:20:00Z"
}
```
---
#### 3.3.3 GET `/items/{itemId}`How to adapt it
- •List your core entities; resources fall out of them.
- •Ask for error-shape and versioning decisions up front.
Have your own rough prompt? Enhance it into a structured prompt like this in one click.
Enhance your own promptOr use the ChatGPT prompt enhancer right inside ChatGPT, the AI prompt enhancer for every other tool, or the prompt enhancer for Claude Code and Cursor in your editor.
More coding prompts
Code Translation Prompt That Preserves Behavior
A structured prompt that ports code between languages idiomatically, flagging behavior differences — with a real example translation.
Coding Interview Prompt for Real Practice
A structured prompt that runs mock interview drills: problem, hints on request, then review of your solution — with a real example session.
Cron Job Prompt That Gets the Schedule Right
A structured prompt that converts plain-English schedules into correct cron expressions with timezone caveats — with a real example.
Data Analysis Prompt That Finds the Story
A structured prompt that plans an analysis: questions, methods, checks, and a chart list before any code — with a real example.
Docker Compose Prompt for Multi-Service Stacks
A structured prompt that writes a compose file with services, networks, volumes, and healthchecks — with a real example file.
Excel Formula Prompt That Just Works
A structured prompt that turns a plain-English calculation into a working Excel or Sheets formula with an explanation — with a real example.