CODEWITHSUNDEEP
urlrestquery-stringuri
Droo
Droo

Reputation: 3205

What to use for space in REST URI?

What should I use:

etc.

The URI represents a Person resource with 1 name, but I need to logically separate the first from the last to identify each. I kind of like the last example because I can do:

Upvotes: 20

Views: 85261

Answers (5)

Philzen
Philzen

Reputation: 4667

The most sophisticated choice should always and first of all consider two constraints:

  1. As you'll never know how skilled the developer or the device being implemented on is regarding handling of urlencoding, i will always try to limit myself to the table of safe characters, as found in the excellent rant (Please) Stop Using Unsafe Characters in URLs
  2. Also - we want to consider the client consuming the API. Can we have the whole structure easily represented and accessible in the client side programming language? What special characters would this requirement leave us with? I.e. a $ will be fine in javascript variable names and thus directly accessible in the parsed result, but a PHP client will still have to use a more complex (and potentially more confusing) notation $userResult->{'$mostVisited'}->someProperty... that a shot in your own foot! So for those two (and a couple of other programming environments) underscore seems the only valid option.

Otherwise i mostly agree with @yfeldblum`s response - i'd distinct between a search endpoint vs. the actual unique resource lookup. Feels more REST to me, but more importantly, the two have a significant cost difference on your api server - this way you can easier distinct and i.e. charge a higher costs or rate limit the search endpoint - should you ever need it.

To be Pragmatic, as opposed to a "RESTafarian" the mentioned approach /people/35-george-washington could (and should imho) basically respond to just the id, so if you want a named, urlsafe-for-dummies-link, list the reference as /people/35_george_washington. Other ideas could be /people/35/#GeorgeWashington (so breaking tons of RFCs) or /people/35_GeorgeWashington - the API wouldn't care.

Upvotes: 1

Nas Banov
Nas Banov

Reputation: 29018

Why not use + for space?

I am at a loss: dashes, minuses, underscores, %20... why not just use +? This is how spaces are normally encoded in query parameters. Yes, you can use %20 too but why, looks ugly.

I'd do 

/personNamed/Joe+Blow

Upvotes: 22

yfeldblum
yfeldblum

Reputation: 65455

For searching:

/people/search?first={first}&last={last}
/people/search?first=george&last=washington

For resource paths:

/people/{id}-{first}-{last}
/people/35-george-washington

If you are using Ruby on Rails v3 in standard configuration, here's how you can do it.

# set up the /people/{param} piece
# config/routes.rb
My::Application.routes.draw do
  resources :people
end

# set up that {param} should be {id}-{first}-{last}
# app/models/person.rb
class Person < ActiveRecord::Base
  def to_param
    "#{id}-#{to_slug(first_name)}-#{to_slug(last_name)}"
  end
end

Note that your suggestion, /findby/name/first/{first}/last/{last}, is not restful. It does not name resources and it does not name them succinctly.

Upvotes: 2

Leventix
Leventix

Reputation: 3869

I like using "_" because it is the most similar character to space that keeps the URL readable.

However, the URLs you provided don't seem really RESTful. A URL should represent a resource, but in your case it represents a search query. So I would do something like this:

/people/{first}_{last}
/people/{first}_{last}_(2)  - in case there are duplicate names

It this case you have to store the slug ({first}_{last}, {first}_{last}_(2)) for each user record. Another option to prepend the ID, so you don't have to bother with slugs:

/people/{id}-{first}_{last}

And for search you can use non-RESTful URLs:

/people/search?last={last}&first={first}

These would display a list of search results while the URLs above the page for a particular person.

I don't think there is any use of making the search URLs RESTful, users will most likely want to share links to a certain person's page and not search result pages. As for the search engines, avoid having the same content for multiple URLs, and you should even deny indexing of your search result pages in robots.txt

Upvotes: 2

Joel Martinez
Joel Martinez

Reputation: 47809

You could always just accept spaces :-) (querystring escaped as %20)

But my preference is to just use dashes (-) ... looks nicer in the URL. unless you have a need to be able to essentially query in which case the last example is better as you noted

Upvotes: 24

Related Questions