HomeCasa Prompts

Design a REST API with an OpenAPI spec

Design a consistent REST API: resources, endpoints, status codes, error format, pagination, versioning and an OpenAPI 3.1 snippet. Designed for ChatGPT, Claude and Gemini. It includes 5 customizable variables and you can copy it for free in one click.

Advanced · Code · Pending editorial review

Designed for:

Prompt

Act as an API architect with experience designing public REST APIs used by third parties.

I am building the API for {{product}}.
Main consumers: {{consumers}}.
Known entities and relationships: {{entities}}.
Non-functional requirements: {{requirements}}.

Deliver, in this order:
1. Resource model: the list of resources, their key attributes, relationships and the identifier each one uses.
2. Endpoint table (method, path, description, required auth, possible status codes). Use plural nouns, at most one level of nesting, and justify any non-CRUD actions.
3. Conventions: field naming ({{naming_convention}}), ISO 8601 UTC dates, cursor-based pagination, filtering, sorting and sparse fieldsets.
4. A single error format based on RFC 9457 (Problem Details), with examples for 400, 401, 403, 404, 409, 422 and 429.
5. Versioning strategy, idempotency (`Idempotency-Key` header on POST) and concurrency control (ETag / If-Match).
6. Security: authentication scheme, permission scopes and rate limits.
7. An OpenAPI 3.1 YAML snippet covering the two main resources, their schemas and reusable error responses under `components`.
8. Design risks and decisions worth reviewing with the team.

Constraints:
- Do not invent business rules: if something is unclear, mark it as [FILL IN] and ask me.
- Favor consistency over creativity.

How to use it

  1. List the entities you already know, even roughly.
  2. Say who will consume the API (mobile app, partners, internal integrations).
  3. Review the endpoint table before asking for the full OpenAPI spec.
  4. Import the YAML into Swagger Editor or Stoplight to validate it.

Usage example

Product: booking platform for clinics · Consumers: mobile app and partners · Entities: clinic, practitioner, patient, appointment.

Sample output

2. Endpoints (excerpt)

MethodPathDescriptionAuthStatus codes
GET/clinics/{clinic_id}/practitionersPractitioners at a clinicclinics:read200, 401, 404
POST/appointmentsCreate an appointmentappointments:write201, 409, 422
POST/appointments/{id}/cancelCancel (non-CRUD action: keeps history)appointments:write200, 409

7. OpenAPI 3.1 (excerpt)

openapi: 3.1.0
info: { title: Clinic Booking API, version: 1.0.0 }
paths:
  /appointments:
    post:
      parameters:
        - { in: header, name: Idempotency-Key, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Appointment' }
      responses:
        '201': { description: Appointment created }
        '409': { $ref: '#/components/responses/Problem' }
        '422': { $ref: '#/components/responses/Problem' }
components:
  schemas:
    Appointment:
      type: object
      required: [practitioner_id, patient_id, starts_at]
      properties:
        id: { type: string, readOnly: true }
        practitioner_id: { type: string }
        patient_id: { type: string }
        starts_at: { type: string, format: date-time }
  responses:
    Problem:
      description: RFC 9457 error
      content:
        application/problem+json:
          schema: { type: object, properties: { type: { type: string }, title: { type: string }, status: { type: integer }, detail: { type: string } } }

Appointment statuses and the cancellation policy are business rules: [FILL IN] before finalizing the status enum…

Key facts

Category
Programming & development · APIs
Output type
Code
Level
Advanced
Designed for
ChatGPT, Claude and Gemini
Verified in
Pending editorial verification
Variables
Product, Consumers, Entities, Non-functional requirements and Naming convention
Language
English
Price
Free, no sign-up
Updated
Nov 7, 2026

Frequently asked questions

Cursor pagination or page/offset?

Cursors stay stable when data changes and scale better on large tables. Offsets are simpler for internal admin screens that jump to specific pages. The prompt defaults to cursors, but you can ask for the alternative.

Can I generate server code from the OpenAPI spec?

Yes. Tools such as OpenAPI Generator create server stubs and clients in many languages. Complete and validate the spec first.

What is this prompt for?

Design a consistent REST API: resources, endpoints, status codes, error format, pagination, versioning and an OpenAPI 3.1 snippet.

Which AI tools does it work with?

It is designed for ChatGPT, Claude and Gemini. We have not verified it in these tools yet, so results may vary between them.

How do I customize the prompt?

Click “Customize” and fill in the variables (Product, Consumers, Entities, Non-functional requirements and Naming convention). The text updates instantly and you can then copy it in one click. Values are stored only in your browser.

Do I need experience to use it?

It is advanced: it is meant for people with experience in the topic who can evaluate and adjust the result.

Is this prompt free?

Yes. Every HomeCasa Prompts prompt is free, with no sign-up or subscription. You can also use them in professional projects.

Can I trust the AI output?

Treat it as a high-quality draft: always check data, figures and important claims before publishing or making decisions.

Related prompts