CODEWITHSUNDEEP
rest
zggame
zggame

Reputation: 999

How to design a REST API for a set of parameters?

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.

Upvotes: 1

Views: 155

Answers (2)

Pedro Werneck
Pedro Werneck

Reputation: 41928

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.

Upvotes: 2

user1907906
user1907906

Reputation:

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

Upvotes: 1

Related Questions