PyAPI: A python library to play with various API Standards, like Hydra, Swagger, RAML and more

Ever been in a situation where your manager asks you to write documentation for the APIs that you developed? Let’s face it, if you’re like most developers, you love to code and hate to write. Furthermore, writing takes time away from critical tasks you need to do, such as feature development and bug fixing.

It’s no surprise that API documentation often ends up being frustrating and confusing for the reader—it rarely gets the attention it deserves.

Hopefully nowadays there are many nice tools to document your APIs. 

Why Document Your APIs?

Let’s start with the non-technical side of the issue. API documentation has been around ever since the first programming languages were created. There’s been plenty of time to develop effective processes for creating quality documentation, yet well-written API documentation is still quite rare. Why doesn’t it happen?

First, documentation is seldom prioritized. Even though it has a large impact on how much a software platform is adopted, the actual impact of documentation is difficult to measure. As a result, documentation is hardly ever given enough time and budget. When developers are asked to write documentation, it’s typically on top of their other responsibilities, and they must somehow fit it into their already overloaded schedule.

Second, developing code and writing documentation are two different skills. Sometimes developers are asked to write in a 
language that’s not their first language. But even if they were born in an English-speaking region and are asked to write in English, there’s a good chance that they struggled through their literature and social studies classes in school, and would’ve much rather spent that time solving problems in their math and science classes.

The first step in creating good API documentation is to ask management for the time and budget to do it well. There are two main points to make to managers:
Good documentation can increase the likelihood of platform adoption because it means a less-frustrating experience for developers.
Good documentation reduces the cost of support because developers can find the answers to their questions more easily.

Arguing the importance of good documentation may be a challenge for you if you don’t enjoy writing or if you’re completely overloaded with work, but there is an alternative. If there’s enough budget, you can hire a technical writer who will gather information from you and write the documentation.

As with developers, you’ll find technical writers with a range of experience and expertise. Many technical writers are more experienced in end-user documentation and support. For API documentation, however, you’ll want to find one who’s actually spent time as a software developer. In many companies, these types of writers have titles like programmer/writer.

Technical writers who have some coding experience under their belt understand the pain that developers go through in trying to get a software platform to work, and how good documentation can help improve the development of the platform. Also, they should have enough specialized knowledge of languages, algorithms and patterns to read your code and understand your libraries. With this knowledge and experience, technical discussion between the writer and development team will be more straightforward and productive.

That said, if the budget doesn’t allow you to bring on a technical writer, then you’ll need to write the documentation yourself. Make sure management understands that you need to carve out time to do this, just as you would for creating a new feature.

PyAPI: Document in Every Possible Format

A while ago I started realising the variety of nice tools out there for designing, testing, consuming APIs, but most of them were developed around a specific technology. Swagger, Raml and API- Blueprints have the most nice toolkits around them.
So, this is more or less when I started thinking. What if I could reuse many of those tools on my API.
For something like this I would need a transformation tool from one API standard to another.
And then I developed PyAPI!

It provides parsers and serialisers for:

• Hydra
• RAML
• Swagger
• API Blueprint
• WADL

The library is hosted in github.
It is still under heavy development and I am trying to develop corresponding use cases and unittests.
Please let me know of your feedback, ideas, anything!

Example Usage

api = API()
api.parse("bookstore.raml", language='raml')

print api.serialise(language="swagger", format="json") 

print api.serialise(language="swagger", format="yaml")

print api.serialise(language="raml")

print api.serialise(language="hydra", format="json-ld") 

print api.serialise(language="hydra", format="n3")