Documentation is missing desciption of custom header usage #45

Closed
haimich opened this Issue Sep 25, 2012 · 22 comments

Comments

Projects
None yet
7 participants

haimich commented Sep 25, 2012

I am evaluating iodocs as a REST documentation tool and I found it quite nice how fast I got a first example running. Unfortunately now I'm struggling with a thing that I couldn't find in any of the readme files: we use certain request headers with our services that I'd like to be present in iodocs. My first idea was to put a section called "headers" in the json description files and insert the required entries, but that only changed the html page to show an expandable headers section with no prefilled entry.

Is there a way to define custom headers and if so: how is the exact syntax in the json file?

I found an example on http://developer.mashery.com/iodocs# that had this feature by setting a "fixed" parameter (Aetna Retail Rx Pricing API).

I'm looking for the same thing. Did you ever get a response?

Actually no, I just want to be able to add a custom header to the request, as in the "Aetna Retail Rx Pricing API" example.

haimich commented Oct 8, 2012

Like TheCodeKing I'm also not looking for any kind of authentication but for the definition of simple http header fields in a request.

Example: my REST service has two properties, @accept("application/json") and @Produces("text/plain"). For a client to be able to call this service he needs to set these two values in the http headers:

Accept: text/plain
Content-Type: application/json

=> Unfortunately I found no way in I/O Docs to define these two headers in the json service file.

PS: No, didn't get a response so far...

Contributor

MarceloEmmerich commented Oct 12, 2012

as a quick work-around, you can hard-code your headers in app.js, line 313. If I find the time over the weekend I will implement this properly (i.e. adding a "headers" section in the apiconfig.json file.

haimich commented Oct 12, 2012

Ok, thanks for your reply!

haimich commented Oct 26, 2012

Any news on this issue?

Regards,
Michael

Contributor

MarceloEmmerich commented Oct 26, 2012

Hey, I issued a pull request a week ago, not sure what happened with it.

Cheers,
Marcelo

haimich commented Oct 26, 2012

Wow ok, sorry I didn't see this. Thanks for your contribution and let's hope that it will find it's way into the master :-)

Contributor

mansilladev commented Oct 28, 2012

I propose the best solution for this would be a "location" property at the method level. Valid values for that property could be "query" (the default behavior now -- a query string), "pathReplace" (replaces placeholders in the URI), and "header" (put into the request header).

haimich commented Oct 30, 2012

Sounds reasonable to me. I'm just not sure if a user of I/O Docs would understand this instantly. What I love about the tool is that everyone can learn how to write the json files in less than 10 minutes. Do you think a simple "headers" section like this wouldn't fit better?

"parameters" : [ {...} ]
"headers" : [ {"Accept": "application/json"}, {"Content-Type": "application/json"} ]
Contributor

mansilladev commented Oct 30, 2012

@haimich The only issue with that proposed schema format is that the key/value pairs are static. To kill both the dynamic/static birds with one stone, we can look at all of these key/values as parameters, and simply place them in the appropriate section with a "location" property. It would be possible to make them "fixed" value (static), or capable of being updated via the form text field.

dgc-wh commented Oct 30, 2012

I like @mansilladev 's idea, though I would argue the property should be a more generic "type" so as not to confuse the "location" term with uniform resource locators.

seneng commented Oct 31, 2012

I also like @mansilladev proposition and more inclined to "location" than "type".

haimich commented Nov 5, 2012

Ok now I'm convinced :-) Who is capable of implementing such a feature? Is there any way I can help?

Contributor

MarceloEmmerich commented Nov 5, 2012

Let me see if I find the time tomorrow. I actually really need this functionality for a current project I'm working on :)

seneng commented Nov 8, 2012

Hi @MarceloEmmerich, did you find the time to implement the feature?
I'm not a dev myself, but happy to help in any way I can.

Contributor

MarceloEmmerich commented Nov 14, 2012

I'm working on it now.

Contributor

MarceloEmmerich commented Nov 14, 2012

I need a publicly available API that requires headers to test-drive this. Does anyone know a good API to add to the three example ones?

Contributor

challgren commented Nov 14, 2012

Requestb.in
On Nov 14, 2012 3:08 PM, "Marcelo Emmerich" notifications@github.com
wrote:

I need a publicly available API that requires headers to test-drive this.
Does anyone know a good API to add to the three example ones?


Reply to this email directly or view it on GitHubhttps://github.com/mashery/iodocs/issues/45#issuecomment-10384627.

Contributor

MarceloEmmerich commented Nov 15, 2012

thanks @challgren, nice tool.

Contributor

MarceloEmmerich commented Nov 15, 2012

I've submitted a pull request with an initial implementation of this. You can now add "Location" : "header" to a parameter for it to be included in the headers sent with the respective method. Due to a lack ob bandwidth, I did not add the fixed/editable flag nor did I add support for specifying other locations (if it's not "header", it defaults to "query").

haimich commented Nov 15, 2012

Thanks a lot for your efforts! I'll try it out with the files you included in the pull request.

haimich closed this Nov 30, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment