4.1 Design for the Consumer
In alignment with the drive of the BPS Result 10 to become more customer-centric, APIs need to be developed with the customer primarily in mind. The application developers also need to be considered because, of course, if the API doesn’t meet their needs then they won’t develop consuming applications that use it. This leads to APIs being developed as generic as possible in order to meet the basic needs of all potential consumers. API developers should not try to predict how the customers will interact with consuming applications, but should leave the application developer to innovate. By designing APIs for the consumer, agencies are likely to build APIs which are intuitive and easy to use, thus ensuring uptake of their APIs and encouraging access to public information.
Initially, application developers will be the main users of APIs. Hence development and delivery of APIs should be geared around making it as easy as possible for developers to discover, understand and develop against those APIs. So APIs, along with the associated on boarding and support processes, should be simple to understand and well described.
Some examples of this principle in action:
Ensure a low barrier to entry so it is easy to start using the API.
Provide sandbox APIs so application developers can try out APIs and develop in parallel.
Be responsive to feedback and bug reports.
Provide automated on boarding processes, as manual processes can limit take-up.
Provide prototyping tools and support for development.
Ensure funding cycle does not introduce a bottleneck for uptake within government.
Sell the concept to the customer early on so they create demand which industry need to meet.
Create an atmosphere of competition in industry for take-up of the API.
Create an SDK to support an agency’s APIs, including examples.
4.2 Design Driven Development
This builds on the principle of "Design for the Consumer" and could also be phrased as "Specification Driven Development" because the interface specification for the API is written first. Designing the interface does not require full design of the code which will sit behind it. The interface can be in place without the functional capabilities being built yet still be useful. By defining the interface first, there is a known integration point, which both the application developer and API provider can refer to and build to. Potential application developers can use the specification to assess whether the API will meet their needs, or if further information or parameters are essential to them. The process of creating a specification before development forces the API developer to properly consider the purpose and content of the interface they are providing, before coding starts. Taking a design driven approach simply means that the API design should be performed before development begins; it does not mean that development is hindered in any way. There are a number of tools that assist with this process, however the tool to create the specification should be of little significance, the act of creating the specification is what counts.
4.3 Co Design
This principle is the natural extension to both “Design for the Consumer” and "Design Driven Development" principles and includes collaborating with the consuming application developer community when designing the interface. This is important to help meet Result 9 aims of making business engagement with government more efficient, not just for business as a customer of government but also where business works together with government. Co Design works as an enabler to business innovation and supports better interaction with government.
Application developers are one of the primary customers for the API and, as such, are a primary source of requirements. Working with application developers to define the requirements and to design the interface ensures the API will meet their needs. However, identifying potential application developers and understanding the demand from the market can be difficult. Careful consideration should be given as to the best approach to engaging with the market and identifying your potential application developer community.
Additionally, it is strongly encouraged that application developers start to produce API consuming applications based on the interface specification as early as possible. This agile or iterative approach helps ensure real-world feedback is incorporated into the API design as early as possible. Completeness is not necessarily the goal, especially in initial APIs. The goal should be to get early partially complete releases out, defining the limited capability they offer, to enable consuming application uptake. Development needs to be flexible and agile to adapt to early adopters’ feedback in identification of pitfalls and issues. However early releases should be tested and stable so as not to impede uptake. The aim is to try, then adapt, rather than waiting to release a fully functional API.
4.4 Future-Focused Design
Most agencies will have a variety of legacy systems that they need to continue to support and service. It is important to remember that business, technology and application architects should be designing for the future of their organisation, and not "hamstring" their APIs under development by designing them to work in the way the legacy system currently works, or to tailor APIs so that they work perfectly with all legacy systems. The aim is to be future-focused (whilst still pragmatic) and develop APIs to meet future needs.
These needs will be agency-specific, but may include a drive to move to a wholesaler rather than a retailer role, where the agency reduces its web presence in favour of enabling commercial entities to create applications, or add richness to existing applications, through access to agency APIs.
4.5 Dogfooding
When building an API, there is always a danger of building the wrong thing in the wrong way for the wrong people. This is especially a risk in the absence of external developers driving or informing the development of the API. The simplest way to ensure an API is useful and consumable is to build the API as part of delivering a larger-scale internal business support system such as a web application. In this way, the customer and application developer are internal, and the first principle "Design for the Consumer" applies.
The best way to design an API is in collaboration with the potential consuming application developers. The best way to understand and address the weaknesses in an APIs design and implementation is to use it in a production system. So, wherever feasible, design an API in consultation with application developers but build it in parallel with an accompanying integration of that API to ensure it is fit for purpose, i.e. build for inside use, then expose. This has the added advantage of meaning that the cost of API development is covered throughout the build of the business support system or integration mechanism, reducing the need for extra funding.
4.6 Stability & Backwards Compatibility
It is important that APIs have stability (are available and work consistently) and support a velocity of change which is acceptable to the application developers. Early versions of APIs should be available via pilots or on developer portals so application developers can work them and identify areas of instability before an API goes into production.
Application developers will not always be able to adapt to new capabilities or changes to existing interfaces as quickly as the API providers might wish, due to organisation priorities and funding. Hence minor changes to APIs must always be deployed as fully backwards-compatible upgrades. For major changes, which are not backwards compatible, the old API version should be maintained alongside the new version for an appropriate period to allow all-consuming applications to transition. By monitoring usage, it should be possible to assess when an API version can be deprecated, either because it is no longer being used or because the usage pattern does not warrant maintaining that particular version. In any case, it is important to clearly communicate with your developer community and manage expectations as to longevity of a particular version of an API.
4.7 Privacy and Sensitivity Aware
APIs are used extensively for passing information, so it is important to consider the information privacy and sensitivity aspects of data being passed to and from APIs to ensure that data is protected adequately. Consideration should be given as to whether a privacy impact assessment and/or a security risk assessment is appropriate for the API during each stage of development, from concept through to implementation. For example, if the API is providing programmatic access to publicly available information, the privacy considerations are likely to be minimal and the security considerations limited to the usual suspects, like the OWASP top 10. However, privacy and security considerations become hugely important if the API is providing programmatic access to private personal information. In this situation, it may be appropriate to do regular assessments, especially early in the concept phase to ensure any privacy or security constraints are understood before design.
There is also the issue that with ease of data consumption comes increased ability to combine data from different sources, which increases privacy risks and the potential for unintended information leakage.
4.8 Well Managed
As API take-up increases over time, there is more likelihood of API change, redevelopment and adaptation to meet new needs. A well-managed API should handle regular change. API management gives an agency the capability to deliver good version control capability and forewarn application developers of changes which may impact them, including failures and outages. For this reason, it is important that all application developers are identified, even if the API is considered public.