Common Reference Doc in Json format

CRDJ.md

Common Reference Doc in Json format

Notice:

• Pages here are all in json format, not normal html page.
• items appears in path are all in lowercase, ex. :modulename
• only fields in bold are the required fields

Doc Site in JSON

Common

The docsite should add Access-Control-Allow-Origin to allow cross json requsest.

• In nginx, it would be add_header Access-Control-Allow-Origin *;

Home -- path: /

Home page defines the main information in your website, which can be your default index page like when visit / in normal website. It should define the following fields:

• name : optional string -- that is the doc name, ex. PHP or MySQL or Javascript
• description : optional string -- description text
• editors : optional array of string -- if any problem on the doc, the guy you can contact with
• uuid : optional string -- used for validating on adding new doc site to goapis.info
• argc : optional integer -- max arguments the site could accept, ex. if it is javascript, the value can be 2 for array/push (class/method) or if it is php, the value can be 3 for curl/curl/curl_init (extension/class or module/function)
• text_format : optional string -- indicate the string format, should be one of text, html, markdown...(if any), defaults to text. It means string type field defined in the doc should be filtered through the string format when viewing in client environment
• index : required string or object -- that is the index of all sub items in tree. If it is a string, it indicates where the data stores (default to __doc__), means if the value is not an object, the client should visit /__doc__ to fetch the index data

Module -- path: (/(:module_name))+

Module Page is used for showing the common information of sub-items, it is very similar like homepage:

• name : optional string -- name of the module, can be uppercase
• description : optional string -- description text
• index : optional string or object -- just like in home page, but it is not required if home page has already defined it.

Api Page -- path: (/(:module_name))+/:api_name

The api name in home or module page must be the value in the index field. Ex.:

// if javascript,
{
	"index": {"array": ["push"]}
}
// if php,
{
	"index": {"curl": {"curl": ["curl_init"]}}
}

• api : required string -- api name
• versions : optional array of string -- the valid versions have the api
• summary : optional string -- a summary text
• grammar : required string -- grammar of how to use the api, ex. array.push(element1, ..., elementN) if it is javascript
• description : optional string -- everything about the api, specially the return value and the explanation of arguments
• examples : optional array of string -- examples for how to use this api
• seealso : optional array of string -- other relevant apis, must have full path, ex. ['/array/push'] relative to your webroot

Client Workflow

1. Request to goapis.info to get the basic info about the doc
2. Client guide user to find the api details by those info

For communicating with goapis.info, here are some common rules:

• Accept field in HTTP header is required, and must equal to application/json
• tags in query string is optional, just for filter purpose, and should be seperated by ,
• the language in tags can be added (following ISO 639-1:2002 is better)
• The index from those doc site could be cachable

Here are the interfaces current goapis.info supported:

Action	Method	Path	Response
list all topics	GET	/	["topic1", "topic2",...]
showing a topic	GET	/t/:topic?tags=:tags	{"name":":topic", "items": [{"url": "http://somewhere", "votes": 100, "tags":[]}, ...]}
search by keys	GET	/search/:keys	[{"url": "http://somewhere", "votes": 100, "tags":[]}, ...]