Posted by mjreich on August 9, 2012 at 2:14pm
Proposing we develop a common /developer module for Drupal. Please chime in with features and requirements you'd like to see.
One of the main requirements of the Digital Strategy is for each agency to implement a /developer section that contains:
- A list of all APIs provided by the office/agency.
- Developer documentation for the APIs.
- A machine readable version of the APIs (for discovery).
This is a great opportunity to use Drupal to build a module that automatically provides the /developer path as well as the other components. Key to this module is ease-of-use: information should be inputted in a series of forms and then the module takes care of display. This will keep the information consistent among all the sites - a much improved experience for developers.
Draft feature list:
- /developer path with a default navigation page.
- Autodetection of APIs
- RSS feeds
- ContentAPI module
- Services module
- Others?
- Space for ToS, Authentication description, links, etc
- Machine readable API list using Swagger syntax (http://swagger.wordnik.com) published at /developer/api.json (or something like that)
What other information/features would be helpful?
Comments
machine Readable API
Is there a particular format that the machine readable API must follow?
Sorry, just read closer about the swagger API.
Yeah, there isn't a specific
Yeah, there isn't a specific API requirement defined in the digital strategy. This is where there's a big opportunity to coalesce around a specific standard. Swagger seems to be building momentum in the wider Web API community.
Alternatives to swagger might include something heavier like WSDL/UDDI, though probably ins't a good fit given the SOAP leanings.
I think the challenge with this type of discovery is finding the balance between simplicity and completeness. I like swagger because its a lightweight solution that seems to include enough information. The auto-generated help docs and API query builder are super helpful developer features.
Have you come across alternatives/approaches you like?
Please no UDDI
I don't have any particular formats that I really like but I do have a serious dislike for UDDI. Way over complicated.
Totally agree :)
Totally agree :)
I've found WSDL's and UDDI
I've found WSDL's and UDDI much less useful in PHP as compared to other languages. My vote is definitely to avoid it if possible.
Does swagger require a server
Does swagger require a server backend to power it?
I was looking at I/O Docs https://github.com/mashery/iodocs but it seems to need node.js which would probably be out of scope for most Government sites at this point.
So there are a couple of
So there are a couple of parts to swagger - the autogenerated description file and the generated human readable documentation package. I think the documentation package requires some sort of server side solution, but it is all based on the description file, which is an open standard any one can implement.
What I was thinking is that we build the /developer Drupal module to implement the swagger description file format, and then auto generate the documentation based on that. But I think the machine readable description is the most important feature for the digital strategy - without it, each agency may end up with their own way to describe APIs.