1

I need to design a REST API to return a resource for a set of parameters. Let us say I need to return a sequence of the numbers, which is determined by three parameters: the generating method, the initial seed, and the scale. The first draft I come up is

(GET/POST) http://url/sequence?method=A&seed=100&scale=5.

The sequence is generated on the fly but is deterministic given the parameter set (A,100,5), so therefore cacheable. But this feels very unrestful. I can maybe change it into

(GET) http://url/sequence/A/100/5.

Which one is better? Or neither is good?

Also, scale might be optional with the default value 1. This is easy to handle as query but not so obvious in URL path. How should I handle it?

I should have added some information of my parameter set. There are only a few "method"s, but there are in principal infinite "seed"s and "scale"s.

Improve this question
1

2 Answers 2

Reset to default
2

RESTful URI is an oxymoron. As long as an URI refers to one and only one resource, it's RESTful. Period. What matters to REST aren't URI semantics, but how clients obtain them. If they are copying URI templates from documentation and not getting them as links, it's not REST. Asking about the RESTfulness of either option doesn't make sense, although you'll find people in endless discussions about what makes an URI more or less RESTful.

However, despite the fact that URI semantics is irrelevant in REST, their readability for developers is important, so your question makes more sense from that point of view. Considering that, I'd say the first option is better, because although URI's are atomic identifiers, it's pretty clear for any developer that the three values are variable parameters, not part of the path. The fact that you have an optional parameter makes it even better.

Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

1

Both URLs are RESTful. But don't use POST if you want to GET a resource.

The optional scale is easy to handle in both URLs.

GET http://url/sequence?method=A&seed=100 GET http://url/sequence/A/100
Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.