Fork me on GitHub

apiculate

apic·u·late: ending abruptly in a small distinct point


Search, filter, and live-query your web service API documentation.

Features

Apiculate is an HTML5 API documentation viewer that allows you to write up your endpoints in JSON, search them, filter them, and send live requests to your server.

{JSON}

Examples

Demo the Gist API as an apiculate view

Demo the apiculate src as an apiculate view

Quick Start

  1. Download the latest release of apiculate.
  2. Host the files on a server. There is an index.inline.html file that allows for easy hosting of apiculate.
  3. Open up the index HTML file for editing.
  4. Drop a <script> tag into the HTML file.
  5. Write a global configuration object to give apiculate your endpoint data.

Example

			
	<!-- your script goes here-->
	<script>		
		window.apiculateConfig = {
		  //let's fill this with JSON!
		  endpoints: [
		    {
		      method: "GET",
			  url: "/index.html",
			  params: [
			    {
				  key: "cachebuster",
				  type: "Number",
				  example: 5
			    }
			  ]
		    }
		  ]
		};
	</script>

Documentation

The Configuration object

hosts Object

The hosts property is a dictionary of URLs keyed by identifiers. This dictionary is used to compose request URLs when live-querying endpoints. Each endpoint can use any one of these identifiers.
endpoints Array

The endpoints property is simply an array of endpoints.

The Endpoint object

method String

The HTTP verb of the endpoint, e.g. GET or POST
url String

The endpoint path. You can include dynamic parts of the path with the paths collection by including <<KEY>> in the string, where KEY is the identifier of the path.
paths Object

This object maps an identifier to an object with data about dynamic parts of an endpoint's path. Each identifier maps to an object with a description,type, and an optional values property.

Valid types are:

  • Number
  • Array
  • String

The values property is used for Array types, and needs to be an array of strings.
host String

The host of this endpoint. Defaults to 'local' which resolves to 'localhost'. You can add additional hosts by modifying the hosts property of the apiculateConfig object.
description String
token Boolean

This is a 'filter-flag' and is false by default. This is meant to signify whether an endpoint requires authorization.
auth Boolean

This is a 'filter-flag' and is false by default. This is meant to signify whether an endpoint accepts a token as authorization.
params Array

This is a list of query parameters for this endpoint. Each entry is a param object

The Parameter Object

key String The key in the key-value-pair of the query parameter.
type String The type of value. Can be one of the following:
  • String
  • Number
  • Array
apiDefault String What the server uses as a default when omitted.
description String
values Array When the type is Array, this array contains possible values.
optional Boolean This is an indicator for whether or not the server requires this parameter.