Icecat API Manual Guidelines

Martijn Hoogeveen
By
guide-through-difficult-terrain-color

This Icecat API Manual Guidelines is written to help to increase the usability and consistency of the manuals and specification of APIs that Icecat is providing to its users. A good specification reads like a manual, and writing the final manual is the final check on the specifications of an API from a usability point of view.

Take care to first read the Iceclog Editor Guidelines, as they are an integral part of these more specific guidelines.

Use English “for Dummies”

API manuals should be in English. Further, an API Manual is not only read by developers, but also by all kind of other staff. So, take care that your manual is written in clear and understandable English “for Dummies”. Make complex stuff simple, so that even non-techy outsiders can understand what it is all about, if they would skip the code sections.

Like any text, have it been checked by a native-English speaker, before publishing it.

Coding by Example

Make it as easy as possible for a user, new to the field, to make use of the API that you describe. Therefore, start with a code example that does the job for one Open Icecat data-sheet. And, expand from there towards the general structure of API calls.

Take care that every attribute is explained. In case that attributes need to be explained, like language codes with extensive tables, take care that these are included by reference and are maintained on a central location.

Self-explaining Code

Developers have the tendency to produce code that is not readable for outsiders, not using complete English words but (weird) abbreviations. Code elements that are not self-explainable, need to be made self-explainable, which makes an API manual more readable as a consequence.

So, don’t say “Lang” for a language code, but say “Language”. Don’t say “No” for an sorting or ordering number, but say “OrderNo”.

Also the terms of the domain should be used consistently, and the semantically most correct terms should be used. Use “BrandName” in stead of the more generic term “Supplier” in case that only the names of product brands are used.

Sometimes values like “200” are dropped in an API call. The reader has to guess that it is for a time-out in seconds, and the techwriter of the manual also doesn’t explain this as he or she didn’t understand it either and forgot to ask.
Better require here “TimeOut=’200′” as a self-explaining attribute.

If you don’t know what something is, ask! Every detail need to be explained.

Use CamelCase

When writing a manual, you will discover that developers have been inconsistent. They might use “Brand_name” in one place, and “BrandName” in another. We want you to make sure during the specification phase already, that the developer has to use CamerlCase (so “BrandName” is correct).

Separate Advanced Options from the Quick Guide

Don’t complicate your manual by immediately introducing advanced options. Better hide advanced options and include them in a separate post. Link to them from the introductory (quick guide) manual.

So, leave out options, functionalities and attributes that are not needed for the most common implementations of the API that you describe. Move these to advanced user sections.

Tips should stand-out

The common mistakes that users of the API and readers of the manual make, should be covered through tips that are not to be missed by the reader. And they should be unambiguous!

Don’t hide your tips.

Visualize!

Show visuals for explaining how the results will look for an end-user of the app. And, visualize the data flow, data model and other key technical elements. Start with end-user visuals. And put technical visuals in appendices as they are there for reference and for a smaller audience.

 Structure clearly

The following structure is required for every Icecat API manual:

  1. An introduction clearly stating the purpose of the manual
  2. A reference to an explanation of Icecat and its services
  3. The key terms used in the manual
  4. The API service explained
  5. API calls explained by example (and references to external examples)
  6. The general structure of API calls
  7. Tips that cover all the typical user mistakes
  8. References to all other relevant manuals and materials including these guidelines
  9. How to get support from Icecat

Featured Image: Sylwia Bartyzel.

Likethumbsup(4)Dislikesthumbsdown(0)

Leave a Reply

Your email address will not be published. Required fields are marked *

open-live-optimized

Manual for Icecat Live: Real-Time Product Data in Your App

Icecat Live is a (free) service that enables you to insert real-time product content from some 300 m...
 June 1, 2016
World map

Iceclog Launch and Improved Icecat LIVE Documentation

“Iceclog” (Icecat content-log) is our new blog, where you will find...
 August 26, 2016
http url

Manual for Icecat URL: Links to Product Data-sheets and Images

Version: 1.20, October 4, 2016.The purpose of this post is to explain the Icecat URL method to ...
 October 4, 2015
open-csv-optimized

Manual for Icecat CSV Interface

This document describes the CSV (Comma-Separated Values) variant of Icecat's Open Catalog Interface...
 September 28, 2016
wall-writer-in-action

Iceclog Editor Guidelines: Writing Compelling Posts

The Iceclog Editor Guidelines are a quick guide for contributors to the Iceclog blog or "cl...
 August 17, 2016
open-personalized-csv-optimized

Manual for Personalized Interface File and Catalog

Via the Icecat website and login area, a user can generate personalized or customized CSV or Excel f...
 October 5, 2016
apple_watch_series1

Apple Watch: a Useful Tool or a Smart Toy?

After six months spent with my Apple Watch, I am still not sure if I consider it a useful tool or "j...
 September 30, 2016

Manual for Testseek Product Reviews Integration via Icecat

Icecat provides aggregated expert reviews from our partner Testseek, as an add-on service for both O...
 October 19, 2015

Manual for Open Icecat JSON Product Requests

JSON (JavaScript Object Notation) is an increasingly popular means of transferring to data, comparab...
 February 17, 2017
ball-752070_960_720

FAQ for Brand Owners

Icecat is an independent global syndicator of rich product content. In...
 October 19, 2016