The aim of this project is to provide a standard API format in JSON which can then be read by libraries in multiple languages (PHP, Python, Javascript, etc). Stage one is PHP due to most familiarity and need for me, and creating API sourcefiles for Last.FM, Twitter, Qwerly, and Linked In to ensure that the format is flexible enough.
For writing an API scheme, see the apis/mobicart.json for the best example. For using an API scheme (none are finished yet), see index.php. For help, email richthegeek@gmail.com
Currently API's often have either no wrapper libraries or a wrapper library that differs vastly across languages (sometimes for good reason, often just different authors). By creating a language-neutral format for defining the capabilities of an API, the hope is to be able to just import that API file using the language implementation of choice (apikit.php, apikit.py, etc) and have a working, familiar wrapper available without hassle.
###Short-term targets:
- Universally readable format for APIs which is flexible enough to allow any RESTful API wrapper to be implemented in it.
- Create formats for Last.FM, Twitter, Qwerly, Linked In.
- Figure out flexible authentication scheme (OAuth is easy if everyone would just implement it please?).
- Implementations in Python, Ruby, Javascript (CoffeeScript).
- More API implementations to ensure flexibility.
- Server and client script-deployment: allow to output a simplified script to langauge of choice which is either a client implementation or the scaffolding for a server implementation.
- Global domination.
WSDL/WADL has somewhat similar aims, and has plenty of inspiration to offer, but it has some major drawbacks, and they mostly stem from XML and the ideas it espouses.
It's clearest when illustrated. Google's Custom Search API method in WADL (I think):
<application xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:yn="urn:yahoo:yn" xmlns:ya="urn:yahoo:api" xmlns="http://research.sun.com/wadl">
<grammars>
<include href="SearchResponse.xsd"/>
</grammars>
<resources base="http://www.googleapis.com/customsearch/v1">
<resource path="">
<method name="GET" id="search">
<request>
<query_variable name="key" type="xsd:string" required="true"/>
<query_variable name="q" type="xsd:string" required="true"/>
<query_variable name="cx" type="xsd:string" required="true"/>
<query_variable name="lr" type="xsd:string" required="true"/>
<query_variable name="alt" type="xsd:string" fixed="json" />
<query_variable name="num" type="xsd:int"/>
<query variable name="safe" type="xds:string" />
<query_variable name="start" type="xsd:int"/>
<query_variable name="filter" type="xsd:int"/>
</request>
<response>
<representation mediaType="application/json" element="ga:items"/>
<fault id="error" status="400" mediaType="application/json" element="ga:error"/>
</response>
</method>
</resource>
</resources>
</application>
In contrast, the same information using STD Rest format:
{
"service" : "Google Custom Search API",
"url" : "www.googleapis.com/customsearch/v1",
"secure" : "always",
"static_fields" : {
"all": ["key={api_key}", "alt=json"]
},
"error_check_path" : "error",
"error_return_path" : "ga:error",
"validators" : {
"lr" : "/^lang_.+$/",
"num" : "/^([0-9]|10)$/",
"safe" : "/^(high|medium|off)$/",
"start" : "/^([0-9]|1[0-9]{1,2})$/",
"filter" : "/^(0|1)$/"
},
"methods" : {
"search" : {
"required" : "q, cx",
"optional" : "lr,num,safe,start,filter",
"path" : "ga:items"
}
}
}
Pros: The code is shorter and more of it is dedicated to the actual API description (less repetition), the validation is stricter/more precise (saves on wasted queries), and various things that are static in the WADL code can be made (using /vars) configurable, such as the "alt" format flag.
Cons: Less descriptive without reference - "query_variable" is obviously a query variable, whereas /methods/*/required/* is not as blatant. Doesn't provide any validation on the data that is returned.
- Implemented the remainder of the Mobicart API (as of Sept 1st)
- Implemented about 50% of the Shopify API
- Redone the hooks system for a broader implementation - see php/hooks.shopify.php for example
- Various bug fixes and minor improvements
- Changed validation syntax (see apis/mobicart.json). Now to add validation to a field you may do it thusly:
- add to method/validation/[key] = [pattern | validators key] (where validators key is a key in @validators)
- add to @validators[key] = {pattern}, where the validators key is the same as the field key
- add to @validators[*] = {pattern, fields: [*,*,key,*,...]} where the fields array (or csv) contains the field key
- Completed the Mobicart API source - with the exception of not having tested the DELETE methods it all works.
- Added a CoffeeScript implementation (minus any attempts at authentication). See readme in that dir
- Fixed one or two bugs with the PHP implementation which regard to handling & and = in keys.
- Added "secure" flag, which can hold "always", "never", or "auth_only", and sets the http/https use in api/rest.
- Added whitespace trimming in CSV values (eg method/required).
- Google Custom Search API as an example.
- Fixed last.fm after regression for v0.02#3
- Various minor bugfixes
- Implemented hooks system for authentication schemes, via @call_hook(hook, data)
- Added "validators" object to spec.
- Changed replacement scheme from %key to {key}
- /static_fields/* all optional
- /url can now hold replacement strings.
- Fixed various bugs
- Further work on Last.FM, specifically authenticated methods
- Initial Mobicart API, fully documented for easier explanation.
- Initial Last.FM api working on simple test cases.
- No Authentication yet, need to figure out how to allow custom auth schemes.
- The apis/lastfm.json should show you well enough how it works, I'll write a proper schema eventually.
GPL - change it however you want, distribute it, whatever. Just don't sell it (although commercial implementors are welcome) or attempt to pass it off as your own.