A major focus of the Constant Contact API v2 release was on making the Constant Contact developer portal an exhaustive resource for developers that ensured they could create innovative, effective integrations with us quickly and easily. One of the anchors of the new portal is the API Docs section. The API Docs are designed to provide reference and conceptual content about the API, including comprehensive documentation of each API endpoint. We give our developers all the information needed for making successful API calls. The Web Services team adopted an innovative way to generate key API documentation elements directly from the JSON schema file developed for each endpoint.

To completely characterize an endpoint, we capture the following information:

• Endpoint Description & associated business logic
• Header and Authentication information
• Path and Query parameters
• Response Codes
• Request & Response body parameters

In the following sections, we describe how we reuse JSON Schema to generate elements of our documentation, and the advantages of this approach.

JSON Schema

The Constant Contact v2 API supports the JavaScript Object Notation (JSON) data interchange format for communicating over the wire. JSON Schema is used to validate JSON payloads and responses passed to and sent from the API. We use a modified version of JSON Schema draft version 3 as specified here.  Here’s the JSON Schema for the ContactList endpoint:

The schema contains all of the information needed to characterize the JSON request and response for the ContactList endpoint. It includes:

• attribute name and type
• boundary conditions (min/max values, string length, enumerations)
• attribute description

Having all this information for an endpoint in a single place makes JSON Schema definition a great resource when creating the user documentation. But we do one better than that, and have re-used the JSON Schema as-is to create the JSON Structure table that defines all Request and Response body attributes.

Keeping Documentation Synced with Code

An obvious advantage of this method is that the JSON Schema is part of the codebase and is always updated by developers when any changes are made to an endpoint, such as extending endpoint functionality. Reusing schema directly allows us to more easily and reliably keep the JSON Structure definitions in the API Docs up-to-date and accurate, which in turn keeps the portal a trusted resource for developers.

Rendering the  JSON Schema

We use a Content Management System to manage the developer portal.  This allows us to merge and render editorial content along with data from our code base to produce the API Doc pages. In our CMS platform, we used a JSON parser along with JavaScript to render the JSON schema file as a table in the API endpoint documentation page, shown here:

Displaying Hierarchical Attribute Relationships

Another advantage of using the JSON Schema is that we can visually represent hierarchical attribute relationships in the JSON data. In this example, several attributes are expandable. This allows us to manage the display of the more lengthy structure tables by collapsing these hierarchies by default and including a visual cue for users to expand these fields to see all child attributes.  Using a CMS platform allows us to modify the look and feel of the documentation and editorial content independent of the Schema files in our codebase. This flexibility is important – if, in the future, we decide to modify the layout of the portal pages, it will not impact the JSON Schema content.

How do you keep your user documentation in sync with your software changes? Let us know.