Using REST design properly - Categories and Subcategories - mysql

Question

I have two question on basic REST concepts.
QUESTION 1: Categories
So I have a list of Categories I want to show from a database.
SELECT * from categories
Currently, I use this REST desgin: /api/v1/categories/
Is that proper?
I have also seen /api/v1/categories/list/ -- or is this preferred? (If so, then what would a simple /categories call display then? (Or would the proper way then be /api/v1/category/list where category is singular and adding list will show you all categories -- this way a call to /category would allow veiwing info on just one?)
QUESTION 2: Subcategories. (Think "Seinfeld" as a subcategory of "Television".)
SELECT * FROM subcategories" WHERE category_id = {id}
The id above might be the Television Category where I want to get specific shows listed.
Would I do /api/v1/categories/{id}/ for the Subcategory with the subcat_id? Would I have to use parameters instead like /Categories?id={id}/
How would this relationship work?

Answer 1

My answers are based on "pragmatic REST".
QUESTION 1: Categories
If you go with plural or singular form then I would suggest sticking with it and not jump between singular and plural... this is subjective.
If you go with singular form, then the list path action sounds applicable. If you go with plural then I think it is more subjective... IMHO list removes ambiguity and I would prefer it.
QUESTION 2: Subcategories. (Think "Seinfeld" as a subcategory of "Television".)
IMHO sub-category sounds like a separate resource. I think it should have its own path element.
Would I do /api/v1/categories/{id}/ for the Subcategory with the subcat_id? Would I have to use parameters instead like /Categories?id={id}/
I think that /api/v1/subcategories/{id}/ is more popular. But one thing that is becoming more popular is searching criteria. ID might just be one of many search criteria. If you see yourself adding search criteria then /api/v1/subcategories/?id={id} or /api/v1/subcategories/?filter={some_search_string} where you decide how that search string is parsed.
The most important thing to consider is that you are able to grow (extend) your API without changing these initial decisions you are making now. Its easy to add to an API but harder to alter existing API design once it is being used.

Answer 2

The URI structure is an implementation detail, it does not matter by REST as long as your service fulfills the uniform interface constraint, which is about applying the relevant standards. In your case the URI structure must fulfill the URI standard and you have to use a hypermedia format, which contains hyperlinks. So in your case /api/v1/sdfh34gsv/123regf3 would be completely okay as long as it is in a hyperlink and there is sufficient metadata available to understand what that hyperlink does. E.g. with HAL+JSON:
{
"_links": {
"/api/v1/docs/rels/category": {
"href": "/api/v1/sdfh34gsv/123regf3",
"title": "Television"
}
}
}
By processing such a response the client will recognize the "/api/v1/docs/rels/category" link relation, so it will know that it is a hyperlink to a category, which title is "Television" and the details of the category can be retrieved by following the link. If the client does not know the /api/v1/docs/rels/category link relation, then it can dereference the URI and and probably it will get some description in RDF, which it can use to display the hyperlink in a more basic form. Ofc, if developers dereference the same URI, they can get a HTML description of the link relation.
By most of the REST services this does not happen, because they use vendor specific MIME types and probably plain JSON, which violates the HATEOAS constraint, but I guess it is more practical in some cases.

Answer 3

async getAllCategorySubCategoryAndGroupCategoryDetail(): Promise < CategoryDetails[] > {
try {
let categoryGroupQuery = `SELECT shrt_category_groups.id as categoryGroupId,
shrt_category_groups.category_group_name as categoryGroupName,
concat('${ENV.IMG_SERVER}',shrt_category_groups.category_group_image) AS categoryGroupImage,
shrt_category_groups.is_active as isActive,
shrt_category_groups.sort_order as sortOrder
FROM shrt_category_groups where shrt_category_groups.is_active = '1' `;
let categoryGroupList = await pool.query(categoryGroupQuery);
if (categoryGroupList.length > 0) {
let categoryListQuery = `SELECT shrt_categories.id as categoryId,
shrt_categories.category_name as categoryName,
shrt_categories.category_image as categoryImage,
shrt_categories.is_active as isActive,
shrt_categories.category_group_id as categoryGroupId
FROM shrt_categories where shrt_categories.is_active = '1'`;
let categoryList = await pool.query(categoryListQuery);
let subcategoryQuery = `SELECT shrt_sub_categories.id as subCategoryId,
shrt_sub_categories.is_active as isActive,
shrt_sub_categories.subcategory_commission as commission,
shrt_sub_categories.commission_type as commissionType,
shrt_sub_categories.sub_category_name as subCategoryName,
shrt_sub_categories.category_id as categoryId
FROM shrt_sub_categories where shrt_sub_categories.is_active = '1'`;
let subCategoryList = await pool.query(subcategoryQuery);
const getCategory = (categoryGroupId: any) => {
return categoryList.filter((cat: any) => cat.categoryGroupId == categoryGroupId)
}
const getSubCategory = (categoryId: any) => {
return subCategoryList.filter((subCategory: any) => subCategory.categoryId == categoryId)
}
let mergeData = categoryGroupList.map((catG: any) => {
return { ...catG,
category: getCategory(catG.categoryGroupId).map((cat) => {
return { ...cat,
subCategory: getSubCategory(cat.categoryId)
}
})
}
})
return mergeData;
} else {
return categoryGroupList;
}
} catch (error) {
throw error;
}
}
{
"data": [
{
"categoryGroupId": 1,
"categoryGroupName": "Cloud",
"categoryGroupImage": null,
"isActive": "1",
"sortOrder": null,
"category": [
{
"categoryId": 1,
"categoryName": "Kinder & Baby",
"categoryImage": null,
"isActive": "1",
"categoryGroupId": 1,
"subCategory": [
{
"subCategoryId": 17,
"isActive": "1",
"commission": null,
"commissionType": null,
"subCategoryName": "Shirts",
"categoryId": 1
},
{
"subCategoryId": 20,
"isActive": "1",
"commission": null,
"commissionType": null,
"subCategoryName": "Jacken",
"categoryId": 1
},
{
"subCategoryId": 21,
"isActive": "1",
"commission": null,
"commissionType": null,
"subCategoryName": "Organic Collection",
"categoryId": 1
},
{
"subCategoryId": 22,
"isActive": "1",
"commission": null,
"commissionType": null,
"subCategoryName": "Baby",
"categoryId": 1
},
{
"subCategoryId": 23,
"isActive": "1",
"commission": null,
"commissionType": null,
"subCategoryName": "Hoodies & Sweatshirts",
"categoryId": 1
}
]
}
]
}
]
}