> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apivalk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RESTful design and naming

> REST principles, HTTP methods, and naming conventions for routes, identifiers, and fields.

# RESTful design and naming

## RESTful design principles

Follow industry-standard REST conventions.

### HTTP methods

| Method  | Description                                            |
| ------- | ------------------------------------------------------ |
| GET     | Retrieve resources                                     |
| POST    | Create a new resource                                  |
| PUT     | Fully update an existing resource                      |
| PATCH   | Partially update an existing resource                  |
| DELETE  | Delete a resource                                      |
| OPTIONS | Show available methods (optional if docs cover it)     |
| HEAD    | Same as GET but returns only headers, no response body |

## Naming conventions

### URI naming

Rules:

* Use plural nouns, lowercase, hyphenated names
* No verbs in URLs
* Nest resources only if there is a logical hierarchy or relationship
* Keep nesting shallow (2 levels max)

Examples:

```http theme={null}
GET    /users
POST   /users
GET    /users/{user_uuid}
PATCH  /users/{user_uuid}
DELETE /users/{user_uuid}
GET    /users/{user_uuid}/authenticators

GET    /user-groups
GET    /user/{user_uuid}/adress-verification-requests
```

### Resource identifiers: IDs vs UUIDs

Path parameters that identify a single resource should (if possible) use UUIDs.

Rules:

* UUIDs should be used for externally exposed REST APIs
* Numeric, auto-increment IDs (/users/1) must not be exposed; they have a risk for enumeration
* Only when there is no other way around it you can use auto-increment IDs
* Internal IDs may exist but should never be part of the public API contract

Rationale:

* Prevents ID enumeration and scraping
* Improves security by design
* Decouples API contracts from database implementation details
* Enables safer data migrations and sharding

Examples:

Correct:

```http theme={null}
GET /users/550e8400-e29b-41d4-a716-446655440000
PATCH /devices/{device_uuid}
DELETE /orders/{order_uuid}
```

Avoid:

```http theme={null}
GET /users/1
PATCH /devices/42
```

### Path parameter naming

Path parameters should be explicitly named:

* {user_uuid}
* {order_uuid}
* {device_uuid}

Avoid generic {id} or {uuid} naming to clarify to what resource the ID belongs to.

### Field naming (JSON bodies)

Use snake\_case:

```json theme={null}
{
  "user_name": "john_doe",
  "email_address": "john@example.com"
}
```

### Parameter naming in URI, path, body

Use snake\_case consistently:

```http theme={null}
GET /users?page_size=50&client_id=123
```

```json theme={null}
{
  "first_name": "Max"
}
```

## How Apivalk Enforces These Standards

Most of the rules on this page are enforced automatically when you use [resource controllers](/resources/index):

* **HTTP methods per mode** — `Route::resource()` picks `POST` for create, `GET` for view/list, `PATCH` for update, `DELETE` for delete. You can't accidentally use the wrong verb for a CRUD mode.
* **Plural URLs** — paths are derived from `$resource->getPluralName()`.
* **Explicit path-parameter naming** — the identifier property name (e.g. `{animal_uuid}`) is used literally in the URL. There's no generic `{id}`.
* **snake\_case fields** — property names on `AbstractProperty` instances are used verbatim as JSON keys; keep them in snake\_case and the API stays consistent.

UUID identifiers are still a developer choice — declare your identifier as a `StringProperty` holding a UUID rather than an `IntegerProperty`.