2012-11-06, revised 2012-11-07

Squiggletronics Module Library API - alpha

In this document variable parts of URLs are shown in caps surrounded by curly braces like this: {FORMAT}


THROTTLING:
If total API traffic exceeds a certain number of hits per minute further requests will be refused and the following header will be sent:
	Status: 503 Service Temporarily Unavailable 
There's also a Retry-After header telling you how many seconds to wait before retrying and a human friendly error message in HTML.
With reasonable caching on your end these usage limits should not be a problem. 

CACHING:
We run a short cache on our end of the API to expedite handling of common requests and reduce load. Currently it's set at 5 minutes. Changes made in the database may take that long to appear in your API results.

FORMAT:
When successful, API results are returned JSON encoded (See http://en.wikipedia.org/wiki/Json)
For the sake of predictability the JSON returned will always be an object (11/7/2012)
Errors are returned using HTTP result codes (404,500, etc)

API URLS:
There is no end slash on the end of an API URL.
The variable parts of the URLs (such as module parameters) is case insensitive.
URLs should be urlencoded. That means all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits and spaces encoded as plus (+) signs. The same way that the posted data from a WWW form is encoded, that is the same way as in application/x-www-form-urlencoded media type. Most languages provide a function for this (PHP: urlencode). 

You'll probably start by getting lists of formats and manufacturers

	http://squiggletronics.com/modlib/api/property/format
	Returns sorted list of format codes (e.g. "E")

	http://squiggletronics.com/modlib/api/property/manuf
	Returns sorted list manufacturers

	http://squiggletronics.com/modlib/api/property/manuf/{FORMAT}
	(put one of the format codes where {FORMAT} is)
	Returns sorted list of manufacturers having modules in a given format

	http://squiggletronics.com/modlib/api/property/format/{MANUF}
	Returns sorted list of format codes for modules made by a given manufacturer
	For instance Modcan now makes modules in three different formats.


Now that you have lists of manufacturers and formats you can request module ids.

About ids:
These module "ids" used in the API are numeric. They are not the same as the "identifiers" defined in the schema.
Squiggletronics identifiers consist of the letter "S" followed by a number.

This URL is used to get ids of modules:
	http://squiggletronics.com/modlib/api/id

It has several forms which retrieve an array of module ids:	
	http://squiggletronics.com/modlib/api/id/{FORMAT}
	http://squiggletronics.com/modlib/api/id/{FORMAT}/{MANUF}
	http://squiggletronics.com/modlib/api/id/{FORMAT}/{MANUF}/{MODEL}
	http://squiggletronics.com/modlib/api/id/{FORMAT}/{MANUF}/{MODEL}/{MODIFIER}
	
The above may be restricted to new modules by using appending a UTC timestamp this way:
	Specifying date:
		http://squiggletronics.com/modlib/api/id/D/YuSynth?after=2012-11-03
	Specifying date and time:
		http://squiggletronics.com/modlib/api/id/D/YuSynth?after=2012-11-03 13:00:00
	With URL encoding that space would become %20 like this:
		http://squiggletronics.com/modlib/api/id/D/YuSynth?after=2012-11-03%2013:00:00
		
	The point of this is to make it easy to periodically check for new stuff, using the date/time from the last time you checked.
	
	
Once you have some id numbers you can get module information with these forms of the URL:
	http://squiggletronics.com/modlib/api/module/{ID}
	http://squiggletronics.com/modlib/api/module/{ID},{ID},{ID}...
	
The data is returned as a JSON encoded array. 
Here's an example:
http://squiggletronics.com/modlib/api/module/11

Here's how that array looks in PHP:
Array
(
    [11] => Array
        (
            [properties] => Array
                (
                    [id] => 11
                    [manuf] => ADDAC
                    [format] => E
                    [model] => 601 Filter Bank
                    [modifier] => 
                    [modtime] => 2012-10-30 01:39:43
                    [HP] => 20
                    [moduleImageFilename] => 1403addac601.jpg
                    [identifiers] => Array
                        (
                            [0] => Array
                                (
                                    [authority] => squiggletronics
                                    [ID] => S110
                                )
                        )
                )
        )
)

The same URL may be used with Squiggletronics identifiers. Like this:
	http://squiggletronics.com/modlib/api/module/{SQUID}
	http://squiggletronics.com/modlib/api/module/{SQUID},{SQUID},{SQUID}...
	
	An identifier "status" code may be returned but most of the time it will be empty.

Here's an example:
http://squiggletronics.com/modlib/api/module/S110

Here's how that array looks in PHP:	
Array
(
    [11] => Array
        (
            [properties] => Array
                (
                    [id] => 11
                    [manuf] => ADDAC
                    [format] => E
                    [model] => 601 Filter Bank
                    [modifier] => 
                    [modtime] => 2012-10-30 01:39:43
                    [HP] => 20
                    [moduleImageFilename] => 1403addac601.jpg
                    [identifiers] => Array
                        (
                            [0] => Array
                                (
                                    [authority] => squiggletronics
                                    [ID] => S110
                                )
                        )
                )
            [status] => 
        )
)



Notes:

modtime - The modification timestamp from the API is expressed in UTC, without leap seconds (see: http://en.wikipedia.org/wiki/UTC).

identifiers and links - We give you these with numeric indexes corresponding to their order in the XML. That's really not important but we like being able to recreate the XML as it was so we keep track of that.
	
	
Coming....	
After this open trial period access to the API may require that you register. 
If you want a feature request it. 

.     .     .     .     .     .     .     .     .     .     .     .     .     .     .     .     .     .

Q&A from users:

Q: The moduleImageFilename field has not much practical value in the result, because people can not access it. Shouldn't this be a link in the future? 
A: That's the name of the image file as receieved by the library. It's not part of the XML. If you're following changes to a particular module it could be helpful. There is not actually a file by that name to link to. The image for the module is always at http://squiggletronics.com/pix/{ID}image.jpg where {ID} is the numeric module id (see [properties][id] in example above).