JSON is a very powerful, open standard format that is used by many services and APIs across the internet. Unfortunately, while open standard carries a lot of good, it also creates some pitfalls that developers may not be prepared to handle.

One of these pitfalls is that, in combination with being widely used, the open source nature leads to fragmentation in how JSON API services are documented. There’s no “standard” method of documentation.

Thankfully, however, there are some good solutions for JSON documentation that represent the best of all words when it comes to this format. Today, we’ll discuss these solutions, as well as what they mean for your documentation as a whole.

What is JSON?

JSON (JavaScript Object Notation)

JSON, or JavaScript Object Notation, is a highly efficient, light-weight encoding scheme that is derived from XML as a response to increasing demands for server-to-browser communication. At the time, in the early 00’s, the only real solutions to the ever-increasing demands for new methods of delivery in the media rich nascent hypermedia web were third party, typically Flash or Java applets, which added unnecessary weight and a barrier to entry for many consumers.

JSON was a natural evolution from Javascript, even though the specification was not formally committed until much later under RFC 4627 — for this reason, “creator” Douglas Crockford has stated he “discovered” JSON rather than creating it.

The main draw behind JSON is the fact that it has lower bandwidth overhead, making it very attractive for high call volume applications or those systems utilizing large size chunks of data. For example, the following is an XML structured credential exchange:

    admin
    default

The same credential exchange expressed in a valid, condensed JSON chunk looks like this:

{"credential":[
    {"username":"admin", "password":"default"}
]}

While on the surface level there doesn’t seem to be much different between the two (and in fact, part of popularity behind JSON is that it’s almost completely interchangeable with XML), the difference in size extrapolated over thousands of lines of code is a huge difference.

More to the point, JSON is by far more readable than XML ever could hope to be in its native configuration. Let’s take another example, this time for a depository of articles, with a single entry being pulled.

First in XML:

   3 Ways to Document JSON API Services
   Kristopher Sandoval
   
      Nordic APIs
      2016
      

While we can see the content somewhat, it’s obscured by archaic structuring and strange characters. This same function in JSON looks quite a bit better:

{
    "blogpost": 123,
    "title": "3 Ways to Document JSON API Services"
    "author": "Kristopher Sandoval",
    "published": {
        "publisher": "Nordic APIs",
        "year": 2016,
    }
}

The second example is shorter, and much easier on the eyes overall — it’s a human readable format, rather than machine readable. While an argument could be made that XML is at its core a language rather than a data format, when the argument between XML and JSON is often discussed, it’s not within the context of using XML as a language, rather as a data format — the API world has, in many ways, moved away from XML towards other alternatives, so the argument is perhaps less valid than it was in the early 00’s when JSON was first being “discovered”.

Now we know what JSON is and why it’s so widely used. But, as JSON is a widely adopted standard in an open source arrangement, there is no single authority for its documentation.

Developers have adopted a wide range of documentation practices for JSON services (and, generally speaking, APIs that respond in a JSON format), each with their own negatives and benefits. Users might be familiar with this sort of problem with Linux — a single open source kernel segmented into hundreds of variations, each with their own variation in documentation and formatting.

While this is in some ways a negative, in others, it’s also a positive attribute — no single authority pushing a centralized documentation approach means developers have a huge range in their methodology, and it really is a “chooser’s market” in terms of solutions.

While there’s certainly been a push towards a centralized approach with efforts like the Open API Specification project, that’s not a true centralization in the way that, say, Swagger has a centralized authority for their specification and detailing. By its very nature, one could argue that a centralized authority would be difficult to establish and enforce.

Use a Third Party Documentation Solution

As is always the case in the tech space, where there’s a problem, there’s a bevy of companies willing to sell you a solution. Some are stronger than others, but they all function on the core principle of translating the underlying structure of your API into an understandable and extensible documentation — which is exactly what we’re looking for.

Solutions like Mashery I/O Docs are great in this particular use case, as they specifically use a JSON schema to describe the API, its resources, methods, parameters, and functions. It will always be easier and more effective to document content in the same language or syntax as the content itself — imagine trying to read a Spanish dictionary written in Mandarin, and you’ll see why this is important.

Of course, you don’t have to stick with the JSON schema. Solutions like the Dexy tool are more general purpose, supporting a wide range of languages and outputting documentation in a variety of chosen schemas. This can work better in situations where the JSON functionality being documented will have to be ported to another data format or interacted with in a legacy environment still utilizing XML.

A big benefit of this approach is the fact that third-party solutions often have a more complete featureset that can make their adoption more valuable. Solutions like Readme.io allow collaborative work, versioning support, and support forums baked in to the solution as a whole, making the documentation a small facet of a larger solution.

These solutions of course add value due to the fact that no development time was used to implement them. This is cost saving, time saving, and effort saving — which is incredibly powerful.

Regardless of which solution is implemented, what’s important is that the content is described in such a way that it can be replicated in the code base itself. Providing examples, live demos, and production resources is also an effective pairing for documentation.

Therefore, in more cases than not (with one such case demonstrated earlier in this text), third party solutions adhering to JSON schema are going to be the average developer’s best choice in documenting these services.

The problem here is that you’re depending on an external resource, passing your code through external documentation devices and platforms. This is fine for general purpose solutions and with trusted companies, but for a more secure, private API harboring trade secrets, this is not an apt choice.

Derive from the Framework

While a third party documentation solution is always on the table, developers can reduce their headache early on by developing within a specific framework that provides automatic or semi-automatic documentation as the API is developed.

These can loosely be considered “third party” in the sense that these frameworks are externally developed; that being said, the underlying code is entirely internal, and thus this solution occupies a second party or business-to-business realm.

Take, for instance, the ever-popular Swagger, which functions as both a framework and a specification. By developing within a specific framework, Swagger users can implement a system that can document the production, consumption, and underlying structure of a RESTful service. More to the point, Swagger is language agnostic, which means it’s often a perfect fit for multi-language or complex systems outputting in a specific data format like those often built upon JSON.

Other solutions like ASP.NET API Explorer utilize your code format itself to automatically generate effective documentation. This is different from a third-party solution in that it is functionally your own code referencing itself. The API Explorer is fundamentally an abstraction layer, and uses branching routing and exploration to document the functionality of an API, which is not only great for documentation purposes, but for error testing and duplication discovery as well.

Of course, all of this hinges on the idea that you’ve built an API that is sound. If you have errors and issues within the code itself, this sort of auto-generation from the framework seems all fine and dandy, but may actually help hide some of these errors, as they’re not made as clear as they would be in either manual documentation or in third party solutions, where error checking is often baked into the system in question.

Create a Manual Depository

Finally, there is the manual approach. This often requires hand-marking or adding markdown to your functions in order to effectively generate documentation. While third-party and framework based solutions could be implemented after the fact, creating a manual depository is best planned well in advance of the API construction itself.

Take for instance the solution from Apiary.io. This service generates API blueprints using specialized markdown, returning simple, readable, and understandable content. For instance, to document a simple function, before the function itself, you’d add the following.

# Article call - calls the article in question with all attached data types

This type of documentation doesn’t require external resources, however — much of it can be achieved physically and manually by the development team in the same manner, but with greater time cost. Creating a wiki or knowledge base is a hands on methodology to generate custom documentation, yet is time consuming.

Markdown

The main point here is to display the functions of each call, and the expected content — while this is easy to do early on in the planning stages, the big downfall to this type of documentation is that it is typically not very adaptive (unless using a markup approach as with Apiary.io). For smaller projects, this is no big deal — for collaborative projects where a feature might go through ten iterations before production, this could be a deal breaker.

All of these solutions boil down to early adoption, however, as retroactively adding markup to all functions and calls may not be the most economical choice given the size and amount of content being tagged. The trade off is that, while the initial overhead is high, you have entire, unrestricted oversight over how your API is documented and how each function is described.

That in and of itself might be valuable enough to forgo any qualms about the time cost involved.

Conclusion: Consider Scalability

What this entire conversation comes down to is this — as with many things in life, your choice is predicated on the nature of the system in question. An API in its nascent beginnings can get away with manual documentation and markup syntaxes quite readily, as the initial cost is somewhat low, especially in smaller APIs and systems.

As you progress, however, you’ll find yourself in a situation where manual documentation takes almost as much time as coding itself. While markup solves this somewhat, you’re still forced to document every change, nuance, and concept in detail.

Framework solutions are very effective, but depend on an adoption of framework. This adoption means you’re tied into an ecosystem which may or may not have long-term support and revision. This means that what time is saved in the initial states will be lost in porting over to a new framework or system.

Finally, third party solutions are great, and work for 99% of cases — they do, however, expose your code base to a third party and rely on the developers of that particular solution.

Each of these approaches has its nuances, and the choice between them rests firmly in what conditions can be bore by the given system.