Address - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: The customer address book — seven customer-facing endpoints. There is no admin surface.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Row-state requirement per route: GET :id works on any state (a customer must see what to restore); PATCH, DELETE and PUT /default require active (409 on archived); restore requires archived (409 on active).

5. Auth, Identity, and Permissions

Rate limits, keyed on the account (keyStrategy: "user"): CUSTOMER_READ 60/min (list/read), CUSTOMER_WRITE 20/min (create/update/archive/restore/default). Idempotency: Idempotency-Key required on create (scope customer-address-create) and restore (scope customer-address-restore).

6. DTO and Model Reference

6.1 CreateAddressDto

6.2 UpdateAddressDto

Same fields, all optional; omitted fields unchanged; an explicit null clears a nullable field. Changing the district may change serviceability, which the response reflects.

6.3 Query DTO

ListAddressesQueryDto: status (active default / archived / all), districtId, provinceId, + QueryDto base (pagination, page, size).

6.4 Response DTO

{
  "id": "0198…",
  "recipient": { "fullName": "Sita Sharma", "phoneNumber": "+9779812345678" },
  "location": {
    "province": { "id": "0198…", "code": "bagmati", "name": "Bagmati" },
    "district": { "id": "0198…", "code": "kathmandu", "name": "Kathmandu" },
    "municipality": { "id": null, "name": "Kathmandu Metropolitan City" },
    "ward": 16, "street": "Jhamsikhel Marg", "landmark": "opposite the bakery",
    "postalCode": "44600", "latitude": 27.6789, "longitude": 85.3123,
    "deliveryInstructions": "call on arrival"
  },
  "status": { "default": true, "archived": false, "serviceable": true },
  "timestamps": { "createdAt": "…", "updatedAt": "…", "archivedAt": null }
}

7. Enum Reference

None — address state is archived_at + is_default columns.

8. Endpoint Reference

8.1 POST /api/mobile/addresses

Purpose

Add a delivery address. The first address becomes the default automatically. Retries with the same Idempotency-Key never create a duplicate.

Auth and Permissions

JwtAuthGuard, IpThrottlerGuard; CUSTOMER_WRITE 20/min (account-keyed); Idempotency-Key required (scope customer-address-create).

Request

Body per §6.1 — local phone accepted (9812345678 → +9779812345678).

Response

201 — address response per §6.4.

Side Effects

customer_address row; auto-default when it is the first active address; serviceability computed from shipping.

Error Cases

8.2 GET /api/mobile/addresses

Purpose

List my addresses — default first, then newest. Unpaginated by default (the active set is capped at 20).

Request

?status=active|archived|all&districtId=&provinceId=&pagination=&page=&size

Response

200 — array of address responses.

8.3 GET /api/mobile/addresses/:id

Purpose

Read one address — archived rows are readable, so a customer can see what to restore.

Error Cases

8.4 PATCH /api/mobile/addresses/:id

Purpose

Update an address. Omitted fields are unchanged; explicit null clears a nullable field.

Error Cases

8.5 DELETE /api/mobile/addresses/:id

Purpose

Archive (soft delete). Archiving the default promotes the newest remaining active address. Restorable via 8.6.

Response

200 message-only.

Error Cases

8.6 POST /api/mobile/addresses/:id/restore

Purpose

Restore an archived address. The default flag is recomputed, never carried over — it becomes the default only if the customer has no other active addresses. Idempotency-Key required (scope customer-address-restore).

Response

200 — address response.

Error Cases

8.7 PUT /api/mobile/addresses/:id/default

Purpose

Make this my default address. Clears the previous default in the same transaction; archived addresses cannot be made default. Concurrent calls are serialized per customer.

Response

200 — address response.

Error Cases

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (create)

9.3 Error Branch (write on archived)

10. Pagination, Sorting, Filtering, and Search

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §8: minimal/full create payloads (§6.1/8.1), success responses (§8.1/8.6), the municipality.id: null response shape (§6.4), domain errors per endpoint (§8 error tables), rate-limit behavior (account-keyed 429), permission-free surface (403 impossible — JWT only).

13.3 API Diagram Pack

Route ownership (§9.1), sequence per endpoint family (§9.2, backend §7), error decision tree (§9.3), serviceability flow (backend §7.2).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, enum, default, transform and validator is documented (§6).
• Every response field and nullable field is documented (§6.4, §8).
• Every auth, guard, permission and guest identity branch is documented (§5).
• Every success, validation, not-found, conflict, rate-limit and server-error branch is documented (§8).
• Every DB read/write, cache read and external call is documented (§11, backend §8).
• Every route has examples for minimal request, success response and representative failures (§8).
• Every endpoint family has route, sequence and error diagrams (§9, backend §7).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (§1, See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/address/backend
• Features and flows doc: /docs/developer/address/feature
• TDD: not yet published