Background

The Hornbill Platform and its various applications are continually developed and evolved to meet the ever growing needs of our customers as well as our strategic objectives that help use remain relevant and competitive. Systems as complex and distributed as Hornbill rely heavily on API’s for communications between front-end and back-end systems, as well as integrations and generally interoperable components which all make use of API’s. As our software evolves rapidly, our API’s also expand and evolve at a similar pace, this is and incredibly important facet of our development process. As a general rule, if an API is only used internally by Hornbill’s own development teams then changing the API’s as requirements evolves is relatively simple, and our development processes are designed for this type of API fluidity.

However, when declaring an API to be ‘’‘Customer Facing’‘’ the rules around those API’s are substantially different. Specifically, Customer Facing API’s: -

• must be supportable, which means it needs to be complete, well-documented, and wholely unambiguous and should not either consume or produce any undocumented data structures like JSON or XML that is not well defined and well documented.
• must provide examples and whatever supporting documentation is required so that the API use becomes self-evident.
• must never expose internal complexities or dependencies, magic numbers of other undescribable things that are not documented.
• must be stable, and only be changed in a way that will not break backwards compatibility with existing uses of this API.
• in the event of an intentional breaking change, it is the responsibility of the development team making the change, to plan and orchestrate communications, migration strategy and supporting documentation.

General Best Practice Guidelines

When creating (or exposing) a customer-facing API, the following best practice guidance should be applied.

• Customer-Specific APIs: It is generally a good idea to create API’s that are specifically designed for customer consumption. While it is tempting to take an existing API and simply expose it to customer use, the problem with doing this comes later when you want to change the product in a way that impacts that API. If you create a customer-specific API, independent of any similar API thats used internally, then you are free to change the internal API’s so long as you maintain the customer-facing API for stability.
• Do Not Use Undocumented JSON Structures: It is common to see undocumented JSON structures being used when browser development is driving the requirements. For example, a third-party component may serialize is data into/out of a JSON structure, and you may want to store this. Or, as often happens, front end developers my need to persist a certain state which invariably means some kind of JSON structure. However, slightly more evil is the case where FlowCode2 scripts expect complex input structures, which are accepted as a JSON-string, and visa-versa, complex output structures also emitted as JSON strings. This leads to basically undocumented API that are developed against by calling the APi and programming the browser based on whats seen in the result. While this practice is not uncommon for internal use-cases where the developer is in control of both the front-end consuming the API and the back-end producing the API, this is wholy unacceptable practice for Customer facing API’s where full and concise documentation of all inputs and outputs are required.
• Provide Ample Documentation: You should properly and fully document each API to the point where using the API is possible with the documentation to hand. Each API should be clearly described for purpose and use cases. If there is any case where a simple string property (input or output) contains a JSON structure, then its critically important that the data strci
• Provide Example Code: Provide enough code examples in the documentation showing how to use the API
• Describe Security Requirements: APIs invariably need specific privileges/rights on the system to operate, these should be clearly declared, defined and explained.
• Reference Dependencies: If an API requires other information, other API’s, concepts or anything else that an API consumer needs to know, you must provide links to documentation for these other things.
• Never Too Much Documentation: The Hornbill platform automates the generation of the basic documentation, and is extensible on an API by API basis so you can provide additional, API-specific information. A customer-facing API can never be over-documented, but can easily be under-documented. Always provide ample, high quality documentation to support the customer facing API’s

Quality Requirements

For internal API’s the quality standards are more relaxed, but for customer facing API’s the following non-negotiable requirements should be met before the API is exposed for customer consumption: -

• Understand Requirements: Understand the needs of your API consumers, start with user research, this will help you structure and write the API documentation based on what your API consumers actually need, do this instead of thinking about the API in the context of our internal needs. Consider your API consumers technical ability, understanding of related topics, and familiarity with terms or acronyms that matter in the context of the API you are creating. You can learn more about user needs and content in the Government Digital Service (GDS) Introduction to Content Design course on FutureLearn.
• Conceptual Overview: Provide a conceptual overview of how your API works, especially if the API is complicated and/or not self-evident.
• Use Correct Data Types: Each input and output parameter should correctly define the datatype it expects. It is not acceptable to just define everything as xs:string because thats the easiest thing to do. The correct declaration of the input/output data type is in its self, part of the documentation.
• Document Every Input Parameter: Each input and output parameter must be adequately documented. If you need to reference other documentation, even on an parameter by parameter basis, this should be done also.
• Single-Purpose Task-Based API: Do not create an API that can do multiple different things depending on what inputs you provide it. The name of the API should reflect its purpose, for example, if you an API that could log a request, and the request could be of different types (say Incident, Problem and Change), its almost always better to create three individual API’s called logIncident, logProblem and logChange, rather than one API called logRequest and a parameter called type that can be set to incident, problem or change. The reason for this is single-purpose API’s are easier to comprehend and document.
• Naming Convention: All API named AND parameters MUST follow the naming convention genreally used in JavaScript, in the camelCaseFormat where the first character is lower case, individual words in the name (apart from the first) are capitalized, and the words describe the function/purpose (see Single-Purpose Task-Based API point above) to the greatest extent possible.
• Stability: Design the API to be stable in the long-term, this means anticipating future roadmap changes and designing the API in such a way that it will most likely continue to be supportable after further changes and evolution.
• Tested: All customer-facing APIs MUST have full test automation applied to each build, ensuring that there are no API breakages deployed into production that causes customers use of the published APIs to break.
• Simplicity: Do not expose internals, magic numbers, magic structures or other such internal things, instead, make the API make sense for the purpose the consumer needs the API for, and do the translations to the more internal esoteric or complex stuff under the hood, abstract away the complexity to make tha API as simple to consume as is possible.
• Defaults: Make sure that as much of the input requirements as possible are optional and have good default values so if the API consumer does not need them, they do not have to specify them.
• Getting Users Started: Provide instructions for use, as well as tested code examples that will be relevant to your API Consumer.