New user questions: handle, reference documentation, licensing? #122

Open
jonathan-sachs opened this Issue Sep 17, 2013 · 1 comment

Projects

None yet

3 participants

@jonathan-sachs

I'm evaluating IODocs for company-wide use. I've got it working with one of our APIs, but I've got some questions.

I've installed it under Linux, and my knowledge of Linux is limited; please excuse me if some of this stuff should be obvious.

  1. In README.md, the text explanations of the API config file examples refer to a property called the "handle," whose value is a URL. I don't see this anywhere in the examples themselves. What is it for, and when is it used?
  2. Where can I find documentation for the elements in config.json and in API config files? READ.md explains the elements that occur in the examples, but I really need a reference that describes all of the elements in a systematic way.

Another example the need for reference documentation is: how to write the API config file for a request that accepts a JSON string? From browsing the support requests I gather that this is supported, but I can't find any information about it.

  1. I know that Mashery offers a licensed version of IODocs as well as the free one that I'm currently using, but I can't find anything about how the two differ, or about licensing terms. Where is that information?
@vky
Contributor
vky commented Sep 18, 2013

This may answer your first question: if you look in the public/data/ directory (https://github.com/mashery/iodocs/tree/master/public/data), you'll see the apiconfig.json and a number of other .json files. In apiconfig.json there's this bit:

"klout": {
    "name": "Klout v2 API",
    "protocol": "http",
    "baseURL": "api.klout.com",
    "publicPath": "/v2",
    "headers" : {},
    "auth": "key",
    "keyParam": "key"
},

The "klout" handle references the 'klout.json' file in public/data/, and lets iodocs setup the URL: http://127.0.0.1:3000/klout. The 'klout.json' file contains the API description for the Klout API.

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