CODEWITHSUNDEEP
ruby-on-railsrest
Humble Objective-Cer
Humble Objective-Cer

Reputation: 123

How to name RESTFUL resources in this case

I am developing a petitions site that is using RESTFul techniques.

For example: /petition/1 indentifies a certain petiton (resource).

How should I name

a) Signing a petition?

/petition/sign/1 or /petition/1/sign or ???

b) Searching for a petition based on terms (rich, for example)

/petition/search/rich /petition?search=rich

And lastly

c) Seeing only a certain category

/petition/category/1 /petition?category=1

Thank you.

Upvotes: 2

Views: 97

Answers (2)

cdeszaq
cdeszaq

Reputation: 31280

As @BrianDriscoll mentioned in his comment, when creating the URLs for resources in a REST architecture, you have to be careful to keep the URLs to being just the nouns (the things in your application) and the verbs are the HTTP methods.

Now that that little bit is out of the way, we can start to dig in to what the nouns in your application really are. From the looks of it, you have essentially 3 "things" (or nouns) in your domain:

  1. Petitions
  2. Petition Signatures
  3. Petition Categories

Assuming that a Petition Signature can only ever be applied to one petition, I would expect the following URL patterns to represent your resources:

  • /petitions - A list of all petitions (the petition root)
  • /petitions/5 - A single petition
  • /petitions/5/signatures - A list of all signatures for a single petition
  • /petitions/5/signatures/7 - A single signature on a single petition
  • /categories - A list of all the categories (the category root)
  • /categories/3 - A single category (which is probably a list of all petitions in the category)

Then, with these resources, you can use the HTTP verbs to manipulate the resources:

  • POST /petitions - Create a new petition
  • POST /petitions/9/signatures - Create a new signature on the petition
  • etc.

Lastly, for searching, you would simply pass a query string to your /petititions URL like so:

GET /petitions?query=blah

The query can be whatever you need for the search engine and it should return a list of petitions that match that query. The same holds true for searching on signatures within a petition or petitions within a category.

This should be enough to get you up and running for now. Ultimately, it comes down to deciding on what "things" and representations of those things your application needs, and then the URLs are just the "names" of those things, much like an address is the "name" of a house. Interacting with those resources (things) is done through the different HTTP verbs.

This is only scratching the surface of the true power of a REST architecture, which includes things like defining content types so that clients know how to navigate your domain, and using hypertext as the engine of application state so that clients can actually do the navigation on a server.

Upvotes: 4

egze
egze

Reputation: 3236

I would do

  • POST to /petitions/1/signatures
  • GET to /petitions?query=rich
  • GET to /categories/1/petitions (assuming you want a list of petitions in a category)

For rails routes it would be:

resources :categories do
  resources :petitions
end

resources :petitions do
  resources :signatures
end

Upvotes: 1

Related Questions