Question

Suppose you are working on an API, and you want nice URLs. For example, you want to provide the ability to query articles based on author, perhaps with sorting.

Standard:

GET http://example.com/articles.php?author=5&sort=desc

I imagine a RESTful way of doing this might be:

GET http://example.com/articles/all/author/5/sort/desc

Am I correct? Or have I got this REST thing all wrong?

Answer 1

You are mostly right. The thing with REST api’s is to focus on the nouns.

What does the noun all do in this case? Wouldn’t you expect your API to always return all articles, unless you filter it?

I would make sort a query string parameters, further, I would make any and all filtering query string parameters. If you look at how Stack is implemented when you click on the “Newest” questions link, you get a query string to filter the questions.

So perhaps something like:

GET http://example.com/aritcles/authors/5?sort=desc

But also think about what happens with each URL:

GET http://example.com/aritcles/ might return all current articles

GET http://example.com/aritcles/authors/ What does this url do? does it return all authors of all articles, or does it return all the articles for all authors (which is essentially the same functionality of the URL above.)

GET http://example.com/aritcles/authors/5/ might return all articles by author 5, or does it return author 5’s information?

I would maybe change it to:

http://example.com/aritcles returns all articles
http://example.com/aritcles/5 returns all articles from author 5
http://example.com/authors returns all authors
http://example.com/authors/5 returns information for author 5