search

okfn / webshot

A web service to take screenshots
http://webshot.okfnlabs.org/
Other
21 stars 13 forks source link

API structure #10

Closed rufuspollock closed 11 years ago

rufuspollock commented 11 years ago

Currently we have:

/api/generate?url ..

Previously we had:

/?url=...

I think for such a simple service we may want to keep it super simple (and easy to remember) in which case the very simple option may be nice:

/?url=

@simong @rossjones what do you think?

rossjones commented 11 years ago

I think /generate?url= gives a clearer idea of purpose, not sure whether the /api/ is necessary or not.

simong commented 11 years ago

I'm with @rossjones, I like to separate out an API endpoint from a regular page. I namespaced it under /api/ in case we'd ever want to add other features.

rufuspollock commented 11 years ago

@rossjones @simong good point though it means that if i'm somewhere online (not at this site) i have to remember the /generate when putting together the url. I guess the question is how often will users want to just use the "API" without going to the site.

At least for me I think it is quite often - e.g. I want to generate screenshots ot insert elsewhere (e.g. google docs). That said I don't how representative i am ...

So to explain: this is a UX question for power users ... (not about url structure for a "normal" API where it won't matter so much since I'll rarely type it myself ...). If this is a real use case than making it as easy to remember as possible is important ...

rossjones commented 11 years ago

How about we just 302 to /api/generate?url= when there are query params, as a default option. We can still keep the namespace and still allow those so inclined to abuse http semantics ;)

rufuspollock commented 11 years ago

@rossjones sounds very sensible ;-)

rufuspollock commented 11 years ago

@simong agree with you on api. Hope you're happy with the small redirect hack i put in to get a slightly more convenient usage :-)