Question

I am designing a restful HTTP API for my application.

The app has Categories which have Products.

I want the users to be able to create a product within a category, and if that category doesn’t exist, then it would be created automatically. So there would be no API for creating the category separately (since I don’t want people to create categories without any products).

I don’t quite get how I should design the API for this. The usual way would be:

1. Create a category:
   POST /categories {"name": "Movies"}
2. Use the new category's id to create a product:
   POST /categories/:id/products {"name": "The Matrix"}

Since I don’t want to expose the first one to the users, how should I let them create the product directly?

Answer 1

Products should probably not be a subordinate resource to categories. Just create the new product with a list of categories that it belongs to, then use the /categories resource to browse the categories. New categories are added as a side effect when a new one appears in a product’s category list.

1. Create product:
PUT /product/the_matrix {"name":"The Matrix","category_list":["movies","science fiction"]}

2. Browse categories:
GET /categories