I'm have the fortunate option to redesign our main project public api. What started as a goal to make a restful api, have [after a lot of extra added features] ended up as a rest/json-rpc mismatch.
So, time to rethink and redesign. However I need some ideas on how to solve some more complex operations.
The basic CURD operations are implemented already and works fine.
Each resource is accessed by hierarchical slugs:
GET /project/fubar/fishes
There are also locale and output formatting added:
GET /project/fubar/fishes.en-us.json
Ok, now to the tricky part:
The basic resource in the project have the similarity to a folder with a title and sub-nodes . A "folder" can have sub-folders and items.
What would be the best practice to add a new folder or an item to a folder?
PUT/PATCH is needed to update the information about the folder, not to link resources to it? POST is needed to create a new folder.
POST /project/fubar/fishes
And to add a bit more, what would be best practice to distinguish the folder to folder and item to folder link operations. Bear in mind that the link can and will have another name then the target. Similar to a symlinks in POSIX systems.
My idea is (to an existing resource):
POST /project/fubar/fishes
{
link: /project/fubar/dogs
title: DOGS!
type: folder
}
And how about the other way around; unlink?
DELETE /project/fubar/fishes/dogs
But is this a good design or will it come back to me later?