A Practical Guide to Designing CRUD APIs

Every time I created a new endpoint, I'd ask myself: "How should I name this route?" It felt like there had to be a set of rules for building consistent APIs. After exploring design diagrams, reading JJ Geewax's API Design Patterns, and studying guidelines from major tech companies, I realized a crucial point:

API design is a distinct discipline with its own principles and standards.

Following established design patterns delivers tangible results:

Developer-Friendly APIs: Uniform patterns and web standards make your API intuitive to use.
Reusability: Both the business logic and the API itself become easier to reuse across projects.
Predictability: The interface remains clear and predictable for external clients and integrations.

The main challenge is that while standards exist, they often vary. Many look great on paper but are hard to apply to a simple CRUD application without complex business logic. This article provides a concise cheat sheet for designing APIs for CRUD services, showing a deliberate and consistent thought process.

Part 1: It All Starts with the Domain

A well-designed API begins with clearly defined resources and their interactions. When your domain model and its operations are clear, the HTTP layer becomes simple and predictable.

The Core Action Vocabulary

To achieve consistency, rely on five fundamental operations in your business logic:

GetResource: Retrieve a specific resource.
ListResources: Retrieve a collection of resources (with filtering, sorting, and pagination).
CreateResource: Create a new resource.
UpdateResource: Modify a resource (partially or fully).
DeleteResource: Remove a resource.

Avoid method names like GetByOrganization, Insert, Upsert, DeleteAll, or FindOrCreate. All variability should be handled through parameters, not by creating new method names.

Part 2: Standard API Methods

The Resource Model

Here is an example model we'll use:

{
  id: guid,
  title: string,
  status: active|archived|draft
}

1. Create a Resource

POST /v1/resources
Request Body:

{ title: New resource, status: draft }

Response: 201 Created with the newly created resource:

{ id: guid, title: New resource, status: draft }

2. Get a Specific Resource

GET /v1/resources/{id}
Response: 200 OK with the resource, or 404 Not Found.

3. Get a Collection of Resources

GET /v1/resources
Response: 200 OK:

{
  resources: [
    { id: guid, title: New resource, status: draft }
  ]
}

Always return an object instead of a raw array. This makes it easier to extend the contract later with metadata or pagination. If no resources are found, return a 200 OK with an empty collection.

4. Replace a Resource (PUT)

PUT /v1/resources/{id}
The request body must contain the full representation of the resource.

{ title: Updated, status: active }

Response Codes:

201 Created: If the resource was created (if you allow client-specified IDs).
200 OK: If the resource existed and was replaced. Return the updated resource.

If a field is omitted from the request, it should be reset to its default value.

5. Partially Update a Resource (PATCH)

PATCH /v1/resources/{id}
The request body should only contain the fields to be changed:

{ status: archived }

Response: 200 OK with the updated resource, or 404 Not Found.

6. Delete a Resource

DELETE /v1/resources/{id}
Response: 204 No Content (with an empty body).

Key Takeaways

Always use plural nouns for resource collections in paths (e.g., /resources).
For standard operations, the resource ID should only be in the path (e.g., /resources/{id}).
Return the full resource on POST, PUT, and PATCH requests to simplify debugging and testing.

Part 3: Extending Standard Methods

Now, let's enhance our basic operations without creating a messy explosion of new endpoints.

Pagination

The simplest and most common method is offset-based pagination using skip and take parameters (or offset and limit).

GET /v1/resources?skip=20&take=10 — Skips the first 20 resources and retrieves the next 10.
Response:

{
  resources: [
    { id: guid, title: ... }
  ],
  total: 350
}

Including total in the response helps the client understand if there are more pages to fetch.
Always sort results by a default key (like creation date) to ensure deterministic responses.
Set a hard maximum limit for the take parameter to prevent performance issues.

Filtering

The most straightforward approach is to use explicit query parameters for each filter. Use operator suffixes for more complex queries:

_eq (default, can be omitted), _ne, _lt, _gt, _lte, _gte
_in, _nin for multiple values

Examples:

GET /v1/resources?status_in=active,draft
GET /v1/resources?title_eq=Design
GET /v1/resources?meta_created_at_gte=2023-01-01

For complex filtering (e.g., on nested arrays), consider a dedicated search endpoint that accepts a POST request with a body.
Ignore unknown query parameters by default.
Use a dedicated search parameter for full-text search.

Sorting

Similar to filtering, use explicit parameters like created_at_sort=asc|desc. If the parameter is absent, the field is not used for sorting.

GET /v1/resources?created_at_sort=asc
GET /v1/resources?created_at_sort=asc&title_sort=desc

Using generic `orderby` or `filter` parameters often leads to parsing headaches and tightly couples the API to the internal data model. Explicit parameters make the contract clearer and simplify implementation.

Soft Delete

Instead of permanently deleting data, mark it as deleted. Add a nullable deleted_at field to your model.

Archive: DELETE /v1/resources/{id} returns 204 and sets the deleted_at timestamp.
Restore: PATCH /v1/resources/{id}/restore returns 200, sets deleted_at to null, and returns the resource.
List with deleted: GET /v1/resources?include_deleted=true.
Permanently delete: DELETE /v1/resources/{id}?force=true returns 204.

Putting It All Together

Here's a request combining pagination, filtering, and sorting:

GET /v1/resources?skip=10&take=5&status_in=active,draft&created_at_sort=desc&include_deleted=false

Part 4: Custom Methods and Batch Operations

Standard GET, POST, PUT, PATCH, and DELETE methods cover about 80% of CRUD needs. The remaining 20% involve custom domain actions that:

Change a resource's state in a way that isn't a simple update (e.g., approve, cancel, apply discount).
Trigger a calculation (e.g., calculate shipping rate).
Have side effects without creating a resource directly (e.g., view resource).

Guiding Principles for Custom Methods

Place a verb after the resource ID: POST /v1/resources/{id}/apply-discount.
Use POST for actions that have side effects.
Use GET for read-only actions like calculations that don't change state.

Batch Operations

Batch operations reduce the number of API calls, allow for atomic changes to multiple resources, and simplify client-side logic.

Batch Read

Avoid passing IDs in the query string, as you risk exceeding URL length limits. Instead, use a POST request.

POST /v1/resources/batch-get

Request Body:

{ ids: [guid-1, guid-2] }

Batch Create

POST /v1/resources/batch

Request Body:

{
  resources: [
    { title: A, status: draft },
    { title: B, status: active }
  ]
}

Response: 201 Created with an array of the newly created resources.

Batch Delete

POST /v1/resources/batch-delete

Request Body:

{
  ids: [guid-1, guid-2],
  force: false
}

Response: 200 OK. According to RFC 9110, it's recommended to use POST with a body for this operation instead of a DELETE method.

Part 5: Frequently Asked Questions

Should I always return the full resource on POST/PUT/PATCH?

Yes. For typical CRUD services, this simplifies development by reducing the need for extra requests. It also makes debugging and testing much easier.

Won't I hit query parameter limits with complex filtering?

For most CRUD applications with a dozen or so explicit filters, this isn't an issue. When you have a large number of criteria, use a dedicated search endpoint that accepts a POST request with the filter parameters in the body.

This guide intentionally omits topics like idempotency, ETags, and versioning, which are well-covered in official guidelines. The goal was to demonstrate that a small, clear set of rules can solve 80% of common API design challenges. By sticking to these principles, you reduce duplication, simplify maintenance, and leave room for future expansion. The other 20% of cases will require thoughtful decisions, and that's when you should consult industry standards.

Useful Links

RFC 9110 — HTTP Semantics (methods, codes, headers)https://datatracker.ietf.org/doc/html/rfc9110
Google API Design Guidehttps://cloud.google.com/apis/design/
Microsoft REST API Guidelineshttps://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md

#restapi #systemdesign