API Documentation Template

[MK]

Hi all -

Does anyone here have a recommendation on an api documentation template/management system?

Thanks.

MK

[mca]

I've by testing Apiary.io and like their approach. It's an early beta so there are warts, but I like it.

mca

+1.859.757.1449
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Andy Berryman]

apiary.io is showing as in closed beta.  Anyone happen to have a code that can be used to sign up with?  I'd like to get in there and check it out.

Andy

--

Andy Berryman
Technical Lead

919.228.4857 office
866.225.3085 fax


2701 Aerial Center Parkway
Morrisville | North Carolina | 27560

www.channeladvisor.com - Be Seen

[Steven WIllmott]

Don't have a code for apiary (but looks cool) - but it's also worth checking out swagger (http://swagger.wordnik.com), which in enabled in our systems at 3scale (http://www.3scale.net). 

 steve.

[Kin Lane]

Hi Andy,

I have access and can send you an invite.

Email me directly at kin...@gmail.com

Kin Lane

[mca]

i have one invite left; email me directly. first one who emails me wins<g>.

mca

+1.859.757.1449
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[mca]

my last invite foir apiary.io is gone :(

i'll try to get more and will post here when it happens.

mca

+1.859.757.1449
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

[Sam Ramji]

+1 for Swagger.

--
Cheers,

Sam

Sam Ramji | Strategy | Apigee | @sramji | +1-510-913-6495

[Philip Ashlock]

There's also I/O docs - https://github.com/mashery/iodocs

I haven't spent time with i/o docs and this is the first I've heard of Swagger, but they seem quite similar. If anyone is familiar with the two, it'd be really helpful to lay out a brief comparison

--
Philip Ashlock

Open Government Program Manager | OpenPlans.org & CivicCommons.org | @philipashlock

[Pablo Molnar]

Hello!

Talking about API documentation I'd like to show to the group the way we've implemented in MercadoLibre's API (http://developers.mercadolibre.com). Basically every API call returns the metadata via OPTIONS verb.

curl -X OPTIONS https://api.mercadolibre.com/sites

All requests with a "text/html" Content-Type are intercepted by a proxy that render a nice browseable html view using the json metada and the actual json api response.

e.g.:

https://api.mercadolibre.com/sites
https://api.mercadolibre.com/items/MLA423426973
https://api.mercadolibre.com/users/2964592

It's more a pragmatic API than a "level 3"/hateoas approach, but we're very proud of it.

Cheers,
Pablo

PS: At the moment we have an enconding issue that we're fixing in the short term.

[Neil Mansilla]

Hi Philip,

I/O Docs is pretty simple. Simple to configure (JSON schema to define your resources/methods) and to deploy (dependencies are few, Node.js, etc.). I'm maintainer of the I/O Docs github repo. Here are a few example deployments to check out -- mind you, these companies just downloaded I/O Docs and deployed it themselves (these are not Mashery clients):

• SendGrid
  http://iodocs.sendgrid.com
  Straight up implementation and here is their JSON config: http://iodocs.sendgrid.com/data/sendgrid.json
  
  
• Datasift
  http://console.datasift.com/datasift
  Straight up implementation -- JSON config is here: http://console.datasift.com/data/datasift.json
  
  
• DocuSign
  http://iodocs.docusign.com
  Customized the code a bit (added objects, arrays and some UI improvements -- optimizing their code before they push their repo public)

Swagger is pretty cool. It's spec is XML based. Requirements are Java, Scala, JAX-RS. Full doc info is here: http://swagger.wordnik.com/swagger-final-1.0.pdf .

Take care,
Neil

[Rob Mullen]

Pablo that is awesome. I've been thinking about doing that same exact thing and thought I invented the concept, turns out I'm already behind the times :).  That's really cool.

[Peter Monks]

<disclaimer>This is something I heard from someone evaluating iodocs - I have not dug into it in this level of detail myself.</disclaimer>

I believe iodocs doesn't deal with binaries at all - it assumes your request and response bodies are 100% JSON.  That may not be a problem in many domains, but is for us (content management - 80% of what we do revolves around bluddy big binary blobs).  I believe DocuSign ran into the same issue and added their own binary support - hopefully that will surface in the "official" version of iodocs at some point.  Is there anyone involved in iodocs development who can comment?

Cheers,
Peter

 

[Andy Berryman]

Yeah ... I second that Pablo.  I've been thinking about doing the same thing.  So you definitely showed me that I'm not crazy!

Andy

[Neil Mansilla]

Hi Peter

Request and response bodies to not have to be JSON. I/O Docs is a simple tool intended to be a way for developers to understand what goes into making a call, and what comes out of the call. Now, if what comes out of a call is a binary response (e.g. image, zip file, etc.) the current view (template based and can be modified) for the response body is a textarea. Adding the capability of rendering an image/video or other type handling any other binary content-type could be fairly simple to hack.

Take care,
Neil

[Peter Monks]

Thanks for the clarification Neil. The issue for us, at least, is that we have as many APIs that receive binaries as we do APIs that return binaries, and we'd love to provide the ability for developers to exercise those APIs as they would our "pure structured data" APIs. Is this on the roadmap for iodocs?

Cheers,
Peter

[Philip Ashlock]

Neil, thanks for the details on iodocs. While I haven't set this up myself yet, we do plan to get it set up for the project I'm working on which is not just one API endpoint, but an API standard that's being implemented by many cities (Open311 GeoReport). A lot of the important work with Open311 right now is building out better tools that not only help more people start working with the API, but help more cities see the value of implementing the standard. Ben Sheldon from Code for America has been building out some of these things lately and is working to customize I/O Docs to work across multiple endpoints simultaneously:

http://iodocs-open311.herokuapp.com/georeport2 - not fully functioning yet (https://github.com/codeforamerica/iodocs-open311)
http://open311status.herokuapp.com/ (https://github.com/codeforamerica/open311status)

If folks are interested in some of the other infrastructure work we're focused on to help this kind of distributed API standard better succeed, you can check out this post:
http://open311.org/2012/01/an-open311-wish-list/

[Pat Cappelaere]

Is there an group objection to using the Google API Discovery service approach and API explorer?
https://developers.google.com/discovery/
No offense to iodocs but it seems to me that the proposed document is really well put together.
I would appreciate group feedback on that?
Thanks,
Pat.

[Neil Mansilla]

Hi Pat,

Indeed -- the Google Discovery Resource format is very nice. It appears to be extensible and quite agnostic. I can imagine spending a weekend or two building support for it in I/O Docs Node.js. Describing resopnses, objects/arrays, references, data types and formatting. Has anyone discovered anything undesirable about it?

Thanks,
Neil

[Daniel Roop]

When I think about the ideal documentation tool, I tend to think it will include three major documentation points.

- Entry Points

- Content Types

- Link Relations

Most of them cover Entry Points, by including all Resources, and Content Type by describing "schemas" of some kind.  I am curious if anyone has seen or knows why the tools dont' include link relations as part of the api specification.  I would imagine it is because the tooling they are trying to generate typically doesn't care about it, because they have a human driver, but I think link rels are very important when programming to an API, otherwise developers bind them self to your resources directly which is less than ideal in my mind.

Thoughts?

[Mike Kelly]

I think the biggest reason these sorts of tools don't come into
existence is because, historically, we've lacked a well-established
interface for expressing links around which that tooling could emerge.

I think we're starting to see this happen now around HAL, e.g:

http://geekswithblogs.net/michelotti/archive/2011/06/06/documenting-link-relations-with-web-api.aspx

There's also the browser I put together to demonstrate how apps
exposed with HAL are 'surfable':

http://hal-shop.heroku.com/hal_browser.html

code for the browser's here:

https://github.com/mikekelly/hal-browser

Cheers,
M

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Pat Cappelaere]

JSON-Schema supports hypermedia links as well.
If we express the discovery document with schemas, links will be described very quickly as we move from a REST API to an Hypermedia API.
Pointing to a user readable documentation is good but will not help much clients that will have no clue regarding semantics of the links... :)
Pat.

[tony tam]

Correction to a previous post--Swagger from Wordnik isn't just XML-based--It's XML or JSON, and is a spec + framework for generating api metadata.  One can produce swagger metadata with a flat file or with tightly-integrated server support.  Currently supports node.js, jax-rs, play, play2, scalatra, php, .net server frameworks, plus ruby, thanks to 3scale contribs.

Swagger is also not tied to a particular API vendor--Klout, IGN, others run large-scale infrastructure on swagger-enabled APIs.

See an overview here http://www.slideshare.net/fehguy/introducing-swagger

Tony

[Andrei Neculau]

bump

anyone else with an invite code to apiary.io ?

[A.J. Brown]

They were pretty quick to send me one after I emailed them asking politely.  I'd give that a try.

Typed with my thumbs.

-- A.J. Brown

[Andrei Neculau]

Thanks!

Indeed they are quick - sometimes you forget the human touch.

Hats off both for what apiary.io does&looks (for now and its potential) and for the guys there.

[Pete Johanson]

These tools all seem to focus on documenting *resources*, instead of
media types, link relations, forms, etc.

What are people's take on this as the focus of documentation? It seem
to me that a tool that would understand various hypermedia types (e.g.
HAL, XHTML, JSON-LD) and allow documenting the media types, link
relations, etc would put the focus on the right concepts.

Thoughts? Any tools out there that do this already?

-pete

On Sat, Jun 30, 2012 at 12:40 PM, Andrei Neculau

[Ed Anuff]

I think that's an important reminder that most successful public APIs
today are resource-based rather than hypermedia-oriented and the
reason these documentation tools focus on that is because that's where
the demand is. The "page of paths" is the documentation expected of
any API provider and the incorrect setting of mime types is the bane
of those tasked with supporting APIs, leading some to ignore the
client-provided media type headers and to assume JSON for all requests
so that the simplest possible curl commands can be used to demonstrate
all API requests.

Ed

[Mike Kelly]

On Mon, Jul 2, 2012 at 3:06 PM, Pete Johanson <lat...@gmail.com> wrote:
> These tools all seem to focus on documenting *resources*, instead of
> media types, link relations, forms, etc.
>
> What are people's take on this as the focus of documentation? It seem
> to me that a tool that would understand various hypermedia types (e.g.
> HAL, XHTML, JSON-LD) and allow documenting the media types, link
> relations, etc would put the focus on the right concepts.
>
> Thoughts? Any tools out there that do this already?

The HAL browser gives you a GUI for traversing through an app that
exposed with HAL. The link relation URIs are clickable and bring up
the corresponding documentation in-line.

This is my preferred approach for documenting a hypermedia API: expose
it with a generic type such as HAL, use URIs for the link relations,
expose documentation at the link relation URIs, and expose a sandbox
version of the application that can be traversed with the HAL browser.

here's an example of dtime using this approach:

http://explorer.dtime.com/

Cheers,
M

[kA]

Does anyone have an invitation for apairy.io? Would be nice to give it a beta test.

Thanks

kA

[KEV]

Does anyone have an invitation for apairy.io?  I like there approach in restful documentation.

Thanks.....

[Owen O Byrne]

Hey Kev,
I just tweeted them and they will give you an invite if you DM them your email. (@apiaryio)
Owen

[Andrei Neculau]

#1. I'm working on you're mentioning. Sometime by the time of the year, it might get to be a "framework" (actually more a example implementation, with some side tools)

#2. Documenting resources and having a mockup-server available as you document those resources shouldn't replace #1, but it is a great complement to it. Especially since the apiary.io syntax comes so natural.

I agree with you on "the right concepts", but I also understand that not all APIs are, nor should be hypermedia driven, and that for a great deal of the cases the semantics of media-types can be provided out-of-band.

A funny comparison: the same way an architect needs detailed plans for a skyscraper, a dad can build a tree-house without ANY plans. And if you look around, many APIs are closer to tree-houses - because of their realities (number of resources, expected spanning time, etc) but also of the importance given to decoupling, data, communication, etc. Just a humble opinion.