Unapaswaje kutaja na kupanga URIs za rasilimali katika REST API?

Question

IT Interview Practice · Accepted Answer

URI ya rasilimali inapaswa kusomeka kama **path yenye msingi wa nomino kuelekea kitu**, si kitendo. HTTP method tayari hutoa kitenzi, hivyo URI inahitaji tu kutambua rasilimali kwa uwazi na mfululizo.

## Kanuni za msingi

- **Tumia nomino, si vitenzi.** `GET /users/42` — si `GET /getUser?id=42`. Method (`GET`) ndio kitenzi.
- **Tumia nomino za wingi kwa collections.** `/users` ni collection; `/users/42` ni mwanachama mmoja. Kubaki wingi kila mahali huifanya itabirike.
- **Iga mahusiano kwa ku-nest** — lakini kwa kina kidogo. `/users/42/orders` = "orders zinazomilikiwa na user 42".
- **Tumia `kebab-case`, herufi ndogo.** `/blog-posts`, si `/blogPosts` au `/Blog_Posts`.
- **Weka filtering, sorting, na paging katika query string**, si path: `/users?role=admin&sort=-created_at`.

## Madaraja yanayolingana

```text
/users                     collection of users
/users/42                  a single user
/users/42/orders           orders belonging to user 42 (sub-collection)
/users/42/orders/1001      a specific order of that user
/orders/1001               same order, addressable at top level too
```

## Mifano

```http
GET /users/42/orders?status=shipped&sort=-created_at&page=2 HTTP/1.1
Accept: application/json
```

Epuka nesting ya kina zaidi ya ngazi moja au mbili — `/users/42/orders/1001/items/5/reviews` huwa dhaifu. Mara order inapokuwa na ID yake, pendelea `/orders/1001`. Kwa vitendo visivyofaa CRUD (mfano "tuma email"), sub-resource ya mtindo wa controller inakubalika: `POST /users/42/verify-email`.

## Kwa nini ni muhimu

Utajaji unaolingana ndio unaofanya API ihisiwe ya kimaumbile — developer aliyeona `/users` na `/users/42` anaweza kukisia kwa usahihi `/products` na `/products/99` bila kusoma docs. Wahoji hutumia hili kupima kama unafikiri kwa **rasilimali** (fikra ya REST) badala ya **RPC calls** (`/doThisThing`). Anti-patterns zinazozoeleka zaidi — vitenzi katika path, wingi/umoja usiolingana, na URLs zenye nesting ya kina — zote hufanya API kuwa ngumu kujifunza na kudumisha, na huashiria developer ambaye hajaiingiza ndani sharti la uniform-interface la REST. Usanifu mzuri wa URI pia huweka mambo yakiwa yametengwa: utambulisho katika path, filtering na pagination katika query string, jambo linaloweka caching na routing safi.

Kanuni za msingi

Madaraja yanayolingana

Mifano

Kwa nini ni muhimu

Maswali yanayohusiana