CODEWITHSUNDEEP
restdesign-principles
ztripez
ztripez

Reputation: 664

Design philosophy and best practies of a restful api

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?

Upvotes: 0

Views: 757

Answers (1)

user647772
user647772

Reputation:

Use Content negotiation

It is not recommended to use this:

GET /project/fubar/fishes.en-us.json

In REST terms, this is a different Resource than those at

GET /project/fubar/fishes

But as far as I understand your question, both are the same Resource, only in different Representations.

To get a Resource in a specific Representation, use Content negotiation.

GET /project/fubar/fishers
Accept: application/json
Accept-Language: en-us

Where are the items?

I don't see any items in your URLs, only what you call 'folders'. In REST terminology, these are called Collection Resources. You add an item to a Collection Resource by POSTing to it. YOu delete an item by DELETEing it. You change parts of an item by POSTing the changed parts to it. You update a complete item by PUTing to it.

I recommend to identify the Collection Resources and the items in your system.

Upvotes: 2

Related Questions