Engineering Spec 06: Categories

Summary

This document aims to provide a baseline on how categories should be implemented to adhere to the SRS documented here.

API Contracts

Standard API contracts are the same as outlined in API Contracts.

Overall categories requirements:

• A category must be able to be linked to a parent category to satisfy the requirement for Menu Systems.
• A category must be able to be queried using a user-friendly slug. The slug should conform to URL-allowed character set.
• There’s an endpoint to query categories in a way that is easily representable on the frontend side.
• Full CRUD endpoints, optionally tested for managing categories.
• All endpoints are documented on Swagger UI.
• Categories should use numeric IDs as primary keys.

All endpoints below are unversioned. In the actual implementation, always use versioned routes.

Slug Generation

Slug is automatically generated by a uniform algorithm to transform category names to lower-case, concatenated with hyphens.

Recursive Deletion

If a category is deleted, then all of its children becomes orphaned, and naturally become a parent category itself. If a category is deleted with products still mapped to it, then all those products are re-classified as uncategorized on the user interface, not on the backend.

GET /categories

Expected results:

1. The categories are not paged. Categories need to be fully displayed on the screen, not paged over like products.
2. Categories have a slug attached with them.
3. The endpoint is safe and idempotent.

Example response:

[
  {
    "id": 1,
    "name": "Electronics",
    "children": [{ "id": 2, "name": "Laptops" }]
  }
]

The response must be in a nested tree form. The response must never contain already marked-as-deleted categories.

POST /categories

Expected results:

1. The request body is validated.
2. The category is created with a resource link pointing to it after.
3. The endpoint must be authorized.

PUT /categories/{id}

Expected results:

1. The request body can be partial, for partial updates.
2. The request body must be validated.
3. The ID must be checked before carrying out the action. This is not an upsert.
4. The endpoint is idempotent.
5. The endpoint must be authorized.

DELETE /categories/{id}

Expected results:

1. The endpoint must ignore the request body.
2. The endpoint must be authorized.
3. The endpoint must be idempotent.
4. The endpoint must not delete the category fully, but a soft deletion.