Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

I was wondering if anyone could lend some advice as to the pros and cons between using Mashery versus Apigee for documenting an API? I have do some evaluating and have about 2 weeks to come up with a proposal as to which to use. I've used Mashery but not Apigee enough to know what the differences are.

Any resources you could point me to or anecdotal advice you could give me would be most appreciated.

I posted this question the API Writers group as well but am cross-posting because this group has a wider audience.

Thank you in advance.

share|improve this question
1  
Welcome to Writers.SE and thank you for bringing your question here! –  Monica Cellio May 14 '13 at 15:10
add comment

1 Answer 1

It's difficult to do a head-to-head comparison because it's not very often that you'll find someone who has experience using both Mashery and Apigee. So, from the Mashery side, I can comment on what is available because I am deeply familiar with the solution.

For documenting an API, Mashery has two product features that come standard to all clients: (1) long form documentation CMS (content management system) with role based access control and (2) interactive documentation (I/O Docs) with full authorization integration.

The CMS for long-form docs is simple. It provides an easy way to build hierarchical docs with a simple WYSIWYG HTML editor, or straight HTML. You also have full style control with CSS templates or even inline injectable CSS, as well as the ability to load remote JS or also perform inline injected JS.

Long form examples:

Tribune Media Services: http://developer.tmsapi.com/docs/read/data_v1/lineups/Lineups_by_zipcode
Expedia Affiliate Network: http://developer.ean.com/docs/read/hotel_list

For the interactive docs, Mashery offers I/O Docs. I/O Docs is configured with a JSON schema, and it's integrated into the developer portal -- so that when a developer is signed in, the authorization schemes and API keys automatically populate. I/O Docs is flexible, and for better or worse, is disjointed from any other API definition, allowing a tech writer to configure I/O Docs to behave not only as a reference doc and testing tool, but also as a learning tool (i.e. step-by-step configuration with detailed descriptions about resources, methods and parameters).

I/O Docs examples:

FoodEssentials: http://developer.foodessentials.com/io-docs (step-by-step style)
Tribune Media Services: http://developer.tmsapi.com/io-docs
EPSN: http://developer.espn.com/io-docs

With Mashery, both the traffic and portal management are performed in one place. It's all very tightly bound together. Of course, that's one of the biggest differences -- the management. Again, for better or worse, Apigee uses Drupal as the CMS, and it operates as a separate unit that needs to be managed. The contrast would be that Mashery's developer portal stack is multi-tenant SaaS, and fully managed.

One individual/company came to mind, Peter from SDK Bridge. I believe his company has written/implemented documentation for one or more Mashery clients, as well as for platforms that are not in the Mashery family. Quite possible he's on here already, but if not, maybe check to see if he'll provide a comparison: http://sdkbridge.com/documentation.php -- he is not associated nor employed with Mashery.

Disclaimer: I am a platforms evangelist with Mashery (an evangelist for our clients' APIs) -- so I know several technical writers and API architects quite well. :)

Good luck!

share|improve this answer
1  
Welcome to Writers! Thanks for the answer, even though you can't cover both sides. If anyone can comment on the Apigee side of things, perhaps we can edit that information into this answer? –  Neil Fein May 14 '13 at 3:24
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.