• Technology
  • 21 February 2020

Three important considerations in API development

You’re thinking about taking a holiday, but before you purchase your air tickets, you decide to use the fare aggregator website Skyscanner to get a sense of how much your flight may cost. Simply by keying in your desired flight dates and clicking on the ‘search’ button, you receive a list of fares from various airlines for comparison. It’s incredibly convenient, but it doesn’t happen magically.

Behind the scenes, application programming interfaces (APIs) are serving as digital ‘messengers’ carrying requests from the Skyscanner website to each airline’s database, then shuttling back with the desired information. APIs are responsible for allowing digital applications to communicate with one another and enabling seamless data sharing among organisations. Content-based systems such as Facebook and Twitter expose web APIs for other systems to easily consume and publish content, while others like Google expose functionalities or features which can be embedded on a website.

At the Government Technology Agency of Singapore (GovTech), we’re harnessing the power of APIs too to create better government digital services for citizens and businesses.

For example, when a citizen uses MyInfo to transact with the government, APIs are running in the background to extract and compile information from multiple data sources. Organisations are welcome to work with GovTech using our NDI {api} platform to tap on MyInfo, as well as collaborate with the government on other digital projects.

If you are building an API library, the MyInfo team would recommend you to consider these three important aspects.

Standards

Good API design is the key to adoption. Just as the USB port helped unify the interface by which electronic devices connect to one another, API standards ensure that digital applications follow a common set of rules and ‘speak the same language’.

The World Wide Web Consortium (W3C) is the international community responsible for defining and updating these standards, which recommend that web APIs be delivered over the Hypertext Transfer Protocol Secure, or HTTPS system. In essence, this means that data is encrypted before being sent over a secure internet connection, SSL certificates for sender and recipient websites are appropriately installed and signed, and domain names check out.

Also, web API responses should be in XML or JSON format. As the term ‘format’ implies, data returned in the response should be structured in a specific way so as to make it readable across multiple web applications. Uniform resource identifiers (URIs)—a string of text or numbers specifying a resource (such as a user profile) should be used as well. Importantly, APIs should be stateless; that is, authentication or authorisation protocols should not depend on cookies or sessions.

Given that APIs may require frequent updates, version control for each API is essential to maintain an organised API library. Following these standards in API development will help expedite the development process while ensuring interoperability between web applications.

Security

Rather than being built in only as an afterthought, security should be integral to the process of API development. This is especially important because very often, APIs are the entry points to your system data or functionality. Like a castle that is protected by a moat, high walls and other internal defences, a multi-layered approached to securing APIs and their associated applications is recommended.

Firstly, network layer security should be in place. This secures the communication channel between applications (e.g. to only allow communications via HTTPS) and prevents programmes known as ‘sniffers’ from illegitimately monitoring network traffic or deciphering data. This should be accompanied by robust application layer security, which acts like bouncers at points where digital applications interact with other network elements, serving to protect against malicious attacks that expose private information.

Another good practice is to enforce IP whitelisting, which involves creating lists of trusted IP addresses or IP locations from which users can access an application. For more sensitive applications, the API should also require user identification, established using different authentication schemes such as Basic Authentication or Open Authorisation.

Documentation

Well-designed APIs without good documentation and support is like a good company without a sales and customer relations department. This is because if the structure and function—and therefore, the value—of an API is not well communicated to someone other than its creator, it will not be adopted or plugged into any application ecosystem.

Good API documentation should be easy to read and interpret, and contain information such as developer environments, URIs, parameters and response formats, security mechanisms and so on. Ideally, documentation should be supported by tutorials, examples and sample codes so that developers can easily integrate the APIs with their applications.

Furthermore, instead of regular content creation and maintenance tools and/or text editors, we suggest using modern and widely adopted standards such as OpenAPI Specification to provide potential developers with a good experience when trying to adopt an API solution.

Finally, nothing is more frustrating than encountering a problem and having no one to reach out to for help. If you are the creator of an API, do leave your contact details and respond to queries from potential users within a reasonable timeframe. Your community will thank you for it.

This article was first published by the Government Technology Agency of Singapore on June 18, 2019. The opinions expressed in this publication are those of the authors. They do not purport to reflect the opinions or views of Bank of Singapore Limited or its affiliates.

Important Information

The contents of this document have not been prepared or reviewed by Bank of Singapore Limited (the “Bank”). The Bank is not responsible for the accuracy or completeness of the information contained in this document which may change without prior notice. This communication may contain views which are not representative of the views of the Bank, and such views may have been derived without discussion, consultation or agreement with the Bank. You will need to decide as to whether or not the contents are suitable for you. When you are in doubt, please seek your own independent financial, legal, tax or other advice as you deem fit. Neither the Bank nor any of its officers accept any liability for any loss whatsoever arising out of or in connection with your use of the information in the document.


Cross-Border Marketing


Brunei: This document has not been delivered to, licensed or permitted by the Autoriti Monetari Brunei Darussalam, the authority as designated under the Brunei Darussalam Securities Markets Order, 2013 and the Banking Order, 2006; nor has it been registered with the Registrar of Companies, Registrar of International Business Companies or the Brunei Darussalam Ministry of Finance. The products mentioned in this document are not registered, licensed or permitted by the Autoriti Monetari Brunei Darussalam or by any other government agency or under any law in Brunei Darussalam. Any offers, acceptances, sales and allotments of the products shall be made outside Brunei Darussalam. Hong Kong SAR: Bank of Singapore Limited is an Authorized Institution as defined in the Banking Ordinance of Hong Kong (Cap 155), regulated by the Hong Kong Monetary Authority in Hong Kong and a Registered Institution as defined in the Securities and Futures Ordinance of Hong Kong (Cap. 571), regulated by the Securities and Futures Commission in Hong Kong. Indonesia: The offering of the investment product in reliance of this document is not registered under the Indonesian Capital Market Law and its implementing regulations, and is not intended to constitute a public offering of securities under the Indonesian Capital Market Law and its implementing regulations. According, this investment product may not be offered or sold, directly or indirectly, within Indonesia or to citizens (wherever they are domiciled or located), entities or residents, in any manner which constitutes a public offering of securities under the Indonesian Capital Market Law and its implementing regulations. Japan: The information contained in this document is for general reference purposes only. It does not have regard to your specific investment objectives, financial situation, risk tolerance and particular needs. Nothing in this document constitutes an offer to buy or sell or an invitation to offer to buy or sell or a recommendation or a solicitation to buy or sell any securities or investment. We do not have any intention of conducting regulated business in Japan. You acknowledge that nothing in this document constitutes investment or financial advice or any advice of any nature. Malaysia: Bank of Singapore Limited does not hold any licence, registration or approval to carry on any regulated business in Malaysia (including but not limited to any businesses regulated under the Capital Markets & Services Act 2007 of Malaysia), nor does it hold itself out as carrying on or purport to carry on any such business in Malaysia. Any services provided by Bank of Singapore Limited to residents of Malaysia are provided solely on an offshore basis from outside Malaysia, either as a result of “reverse enquiry” on the part of the Malaysian residents or where Bank of Singapore Limited has been retained outside Malaysia to provide such services. As an integral part of the provision of such services from outside Malaysia, Bank of Singapore Limited may from time to time make available to such residents documents and information making reference to capital markets products (for example, in connection with the provision of fund management or investment advisory services outside of Malaysia). Nothing in such documents or information is intended to be construed as or constitute the making available of, or an offer or invitation to subscribe for or purchase any such capital markets product. Myanmar: This document and information herein is made available by Bank of Singapore Limited, which is not licensed or registered under the Financial Institutions Law (Law No. 20/2016) or other Myanmar legislation to carry on, nor do they purport to carry on, any regulated activity in Myanmar. The provision of any products and services by Bank of Singapore Limited shall be solely on an offshore basis. You shall ensure that you have and will continue to be fully compliant with all applicable laws in Myanmar when entering into discussion or contracts with Bank of Singapore Limited. Oman: This document does not constitute a public offer of investment, securities or financial services in the Sultanate of Oman, as contemplated by the Commercial Companies Law of Oman (Royal Decree No. 4/1974), Banking Law of Oman (Royal Decree No. 114/2000) or the Capital Market Law of Oman (Royal Decree No. 80/1998) and the Executive Regulations of the Capital Market Law (Ministerial Decision No. 1/2009) or an offer to sell or the solicitation of any offer to buy non-Omani investment products, securities or financial services and products in the Sultanate of Oman. This document is strictly private and confidential. It is being provided to a limited number of sophisticated investors solely to enable them to decide whether or not to make an offer to invest in financial products mentioned in this document, outside of the Sultanate of Oman, upon the terms and subject to the restrictions set out herein and may not be reproduced or used for any other purpose or provided to any person other than the original recipient. Additionally, this document is not intended to lead to the making of any contract within the territory or under the laws of the Sultanate of Oman. The Capital Market Authority of Oman and the Central Bank of Oman take no responsibility for the accuracy of the statements and information contained in this document or for the performance of the financial products mentioned in this document nor shall they have any liability to any person for damage or loss resulting from reliance on any statement or information contained herein. Russia: The investment products mentioned in this document have not been registered with or approved by the local regulator of any country and are not publicly distributed in Singapore or elsewhere. This document does not constitute or form part of an offer or invitation to the public in any country to subscribe for the products referred to herein. South Korea: The document does not constitute an offer, solicitation or investment advertisement to trade in the investment product referred to in the document. The Philippines: The information contained in this document is not intended to constitute a public offering of securities under the Securities Regulation Code of the Philippines. Dubai International Financial Center (DIFC): Bank of Singapore Limited has a branch registered in the Dubai International Financial Centre ("DIFC") which is regulated by the Dubai Financial Services Authority (“DFSA”). Bank of Singapore Limited (DIFC Branch) is not a financial institution licensed in the United Arab Emirates outside of the DIFC and does not undertake banking or financial activities in the United Arab Emirates nor is it licensed to do so outside of the DIFC. This material is provided for information purposes only and it is general information not specific in any way to any particular investor, investor type, strategy, investment need or other financial circumstance. As such this information is not financial advice or a financial promotion, nor is it intended to influence an investor's decision to invest. It is not to be construed as an offer to buy or sell or solicitation of an offer to buy or sell any financial instruments or to participate in any particular trading strategy in any jurisdiction. The material is only intended for persons who fulfill the criteria to be classified as “Professional Clients” as defined under the DFSA rules and should not be reviewed, received, provided to or relied upon by any other person. United Arab Emirates (U.A.E): The information contained herein is exclusively addressed to the recipient. The offering of certain products in this document has not been and will not be registered with the Central Bank of United Arab Emirates or Securities & Commodities Authority in the United Arab Emirates. Any products in this document that are being offered or sold do not constitute a public offering or distribution of securities under the applicable laws and regulations of the United Arab Emirates. This document is not intended for circulation or distribution in or into the UAE, other than to persons in the UAE to whom such circulation or distribution is permitted by, or is exempt from the requirements of, the applicable laws and regulations of the United Arab Emirates. The distribution of the information contained herein by the recipient is prohibited. Where applicable, this document relates to securities which are listed outside of the Abu Dhabi Securities Exchange and the Dubai Financial Market. The Bank of Singapore Limited is not authorized to provide investment research regarding securities listed on the exchanges of the United Arab Emirates which are outside of the DIFC. United Kingdom: In the United Kingdom, this document is being made available only to the person or the entity to whom it is directed being persons to whom it may lawfully be directed under applicable laws and regulations of the United Kingdom (such persons are hereinafter referred to as ‘relevant persons’). Accordingly, this document is communicated only to relevant persons.  Persons who are not relevant persons must not act on or rely on this document or any of its contents. Any investment or investment activity to which this document relates is available only to relevant persons and will be engaged in only with relevant persons. Relevant persons in receipt of this document must not distribute, publish, reproduce, or disclose this document (in whole or in part) to any person who is not a relevant person. United States of America: This product may not be sold or offered within the United States or to U.S. persons.

© 2019 Bank of Singapore Limited. All rights reserved.

Version: December 2019