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.
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
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.