API versioning

The Silk API consists of three separate layers: the REST API, the document format and the component metadata. By using a versioning scheme per layer we minimize the chance of breaking existing projects when making small changes to the API.

Facts collected from tagged text on this page
Facts about this page

Silk has a powerful API that allows for the full creation and modification of all of the aspects of a Silk site. Our own client is built on top of this same public API, without using any special backdoors.

To minimize the chance of breaking existing projects when changing the Silk API we introduced a layered interface, where every layer has its own versioning scheme. The Silk API is nicely separated into three different layers:

  1. The Silk REST API. The top layer is our REST API as documented here. Our REST interface is of a pretty common design, a hierarchical collection of HTTP endpoints to access Silk resources. We use HTTP GET for read-only access to resources, PUTs for creation and POSTs for actions that might have side effects. Most endpoints support input and output using both XML and JSON. This part of the API is versioned with a version number in the URI. At the time of writing the current version is 1.12.5. For example, accessing the list of available sites can be done using https://api.silk.co/v1.12.5/site. We try very hard to not break older API versions and we actively support older versions as long as we think is feasible.



  2. The Silk Document Format. The second, but equally important layer of the API is the format of the Silk documents. The Silk document format is a rich format that uses HTML for the overal document structure and JSON for enrichment with custom metadata. We use custom HTML5 data attributes to store JSON metadata about images, layout, components, etc. So, Silk's document format is very much like HTML5, but enriched with metadata for both added semantics and interactivity. The document format has a version number as a data-format attribute on the top level article element of the document. (Note that while Silk documents are structured like HTML5 documents, they must syntactically be valid XML before being accepted by our server.)



  3. Silk Component Metadata. All the interactive parts of a Silk page are created using components. The fact-sheet is a component, tables, maps, charts and other widgets are components, but also images and text blocks are components. To avoid changing the Silk document format version every time we make a small change to the metadata format one of the components we introduced a version per component. The version number is reflected in the unique identifier placed on the component element using the data-component-uri attribute.

The recent release of our new explore page included an overhaul of the layers 2 and 3 of our API, the Silk document format and the component metadata. All old documents will transparently be migrated to the new format. Because the new format is much cleaner and far more usable than our old format, we decided to deprecate the old format and no longer support it.