webpipes/spec

Proposal for POST requests on /block-endpoint

Opened this issue · 5 comments

jpf commented

The spec defines expected behavior:

>>> POST /block-endpoint
>>> Content-Type: application/json
>>> …more headers…
>>> {"input": {"foo": "Value for foo input", "bar": "Value for bar input"}}

<<< 200 OK
<<< Content-Type: application/json
<<< …more headers…
<<< {"output": [{"baz": "Value for baz output", "qux": "Value for qux input"}]}

However, for people who are manually exploring the API (with curl, for example) I propose that we define how webpipe endpoints would respond to unexpected input:

>>> POST /block-endpoint
>>> Content-Type: application/x-www-form-urlencoded
>>> …more headers…
>>> test=true

<<< 400 BAD REQUEST
<<< Content-Type: application/json
<<< …more headers…
<<< {"output": [{"error": "webpipe input expected", "more-details": "http://example.com/error/input-expected"}]}
progrium commented

Hmm. Well self-description is part of the protocol. Right now that would be with the OPTIONS verb. I'm torn though because if it where a different URL, I could imagine referencing it in an error to a bad request, but it seems like it should be clear to use the OPTIONS verb.

jpf commented

I'm not tied to a particular implementation. Just proposing a gentle nudge of some sort to developers who aren't used to OPTIONS yet.

jpf commented

As an aside, how does one make an OPTIONS request with curl(1)?

progrium commented

True. Command line tools will either tell you how to use help or display it
in place when you use it wrong. I think that's a good pattern.

On Wed, Nov 28, 2012 at 2:28 PM, Joël Franusic notifications@github.comwrote:

I'm not tied to a particular implementation. Just proposing a gentle nudge
of some sort to developers who aren't used to OPTIONS yet.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1#issuecomment-10825969.

Jeff Lindsay
http://progrium.com

progrium commented

-X/--request

curl -X OPTIONS http://example.com

On Wed, Nov 28, 2012 at 2:29 PM, Joël Franusic notifications@github.comwrote:

As an aside, how does one make an OPTIONS request with curl(1)?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1#issuecomment-10826029.

Jeff Lindsay
http://progrium.com