36) This section is intended to provide guidance on industry best practices around the design, security, maintenance and use of APIs in order to ensure interoperability, resilience and scalability of the API economy that we wish to encourage in ADGM and with other international API implementations.
    37) It is recommended that an organisation should first identify why it wants to develop and provide (or consume) an API, who the stakeholders within the organisation are, who the audience for the API will be, the systems and business processes involved and the actors/system that the API will interact with or replace.

    • Design

      38) All APIs should:
      a. Have platform independence – any web or mobile client should be able to call and interact with the API, regardless of how the API has been implemented internally.
      b. Allow for unhindered API evolution – APIs should flexibly evolve and be able to add functionality independently from other applications using them. As the APIs evolve, the existing applications using them should be unaffected and can continue to function without having to update to the latest version of the API.
      c. Use appropriate data standards – APIs should be using the most relevant data standard that are applicable for the type of data being transacted and the use case it is being applied to. Where there is no fit within an existing data standard organisations may decide their own data specification. However, it should publish the associated definitions using a ‘data dictionary’ in line with industry practices such as those outlined in the Open API Specification or Web Service Definition Language.
      d. Have good data security - It is important to have stringent information security, cyber security and other data related policies/guidelines.
      e. Be complete and concise – an API should be easy to understand and work with, as should be the API contract. Implementing and integrating with it should be a straight forward process.

    • API Documentation

      39) The API documentation (or ‘contract’) describes all aspects of the API in order to enable successful interaction between the API provider and API consumer. As such it should be a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, and arguments. The API contract should, where relevant, be supported by tutorials and examples.
      40) At a high level the fundamentals that need to be documented in the API contract in order for both parties to be able to interact are:
      a. The business rules and service agreed between the API Providers and Consumers.
      b. The rules around how each party authenticates themselves before gaining access to the API.
      c. The standards that the API is adhering to including the change management and version control information that the consumer must be aware of.
      d. The design of the API i.e. its structure, the resources (data) that it provides access to and how to interact with the API to obtain them.
      e. The certification, on-boarding and acceptance of the API consumer from the API.
      41) As such the API contract should also include the following content (but not be limited to):
      •   sampling code and example responses
      •   rules on information handling, incident management and risk management
      •   method of authentication (and how it impacts service interoperability, single sign-on, and rate-limiting)
      •   design changes (recent and planned) and versioning information
      •   availability, latency, ownership, depreciation policies and status capability
      •   approach to backwards compatibility
      •   guidance on configuring the API to make sure any relevant governance frameworks are followed
      •   the open data standards used
      •   security information
      •   cost of use of the APIs, if applicable
      •   support that will be provided to the consumer of the API

    • Security

      42) Most important of all the considerations for organisations providing and consuming APIs is the security measures that are deployed, which must comply with network security best practices. Updates and patches to all systems, particularly security systems, should be performed as soon as safely feasible after such updates and patches have been released. The following sections set out the main risk areas and mitigations for these that, in the opinion of the FSRA, need to be taken into account.
      43) As a general rule organisations providing and using APIs should also ensure that all parties that they are engaging with:
      •   Use access tokens to establish trusted identities and control access to the services and resources.
      •   Encryption and signatures are employed as standard.
      •   Quotas and throttling are in place that determine how often APIs can be called. For example, more calls on an API may indicate that there is a Denial-of-Service attack. Or it could also be a programming mistake such as calling the API in an endless loop.
      •   API traffic is enforced using an API gateway that allows authentication as well as control.
      44) For more detailed technology standards that should be employed please see Appendix B.

      • Cyber security

        45) As APIs are another entry or exit point for an attack on an organisation, the API security strategy must include the following cybersecurity mitigations (but not be limited to):
        •   Strong firewall defences
        •   Vulnerability and threat management
        •   Antivirus and malware protection
        •   Denial of Service (DoS) or Distributed Denial of Service (DDoS) protection
        •   Patch management
        •   Email filtering
        •   Web filtering
        •   Administration privileges
        •   Access control
        •   Intelligence and information sharing

      • Encryption

        46) The encryption of data, both at rest and in transit, should be included in the security policy. In particular, encryption and decryption of private keys should utilise encryption protocols, or use alternative algorithms that have broad acceptance with cyber security professionals. Critical cryptographic functions such as encryption, decryption, generation of private keys, and the use of digital signatures should only be performed within cryptographic modules complying with the highest, and ideally internationally recognised, applicable security standards.

      • Two-factor authentication

        47) As well as ensuring that architecture supporting the API and the API itself is secure, organisations should also consider the use of two-factor authentication (2FA) when APIs are initiated by a consumer accessing online service. 2FA is an extra layer of security designed to ensure that the only person who can access an account is the individual who owns it, even if the individual’s password has been compromised. The process involves the user providing two different authentication factors to verify themselves.
        48) However, it is worth noting that whilst this reduces the chance of being hacked, 2FA is not completely secure and still relies on the vigilance of the individual. For example, phishing attacks purportedly coming from trusted services login page can result in users giving away their credentials. In some extreme cases, hackers have been able to negate 2FA by spoofing an individual’s SIM card and intercepting the unencrypted message as it is sent over the network.

      • Penetration testing

        49) It is recommended that all systems and infrastructure should be regularly tested for vulnerabilities by an external penetration testing expert who is professionally accredited (such as CREST, IISP, TIGER scheme or OSCP Offensive Security).

      • Credentials management

        50) Authentication, authorisation and encryption are fundamental to the security of APIs. In terms of authentication, as far as possible, API providers should have a well-defined process to help ensure that individuals or organisations are robustly authenticated.
        51) Authorisation should only allow the authorised/accredited organisations and people to have access to the right API resources.
        52) Organisations must therefore ensure that they have the appropriate infrastructure in place for secure storage and management of relevant access credentials. These credentials include (but not limited to):
        •   Identity keys
        •   Signing keys
        •   OAuth client IDs and secrets
        •   Usernames and passwords
        •   Access tokens
        53) Where authentication processes are handed off or redirected to other sites or apps, the technical processes should avoid the potential for disclosure or interception of the credentials. The organisation should also maintain the ability for the user to verify the authenticity of the site into which they are entering their credentials such as displaying the relevant URL and lock icon that they are interacting with.

      • Monitor API activity

        54) The security of an API is only as good as the organisation’s day-to-day security processes. All APIs should be monitored for unusual behaviour such as changes in IP addresses or users using APIs at unusual times of the day.
        55) It is recommended that the ability to write audit logs before and after security related events is in place as this increases the potential to monitor and detect attacks.
        56) Larger organisations should also look to create a Security Operations Centre (SOC) dedicated to monitoring, assessing and defending enterprise information systems such as APIs, web sites, applications, data servers, networks, hardware and software.

      • Error handling

        57) All responses to errors should use the commonly used HTTP codes and should not reveal details of the failure unnecessarily as this may provide unintended attack vectors for bad actors.

    • Data

      To enable the interoperability of APIs at all levels (whether among systems, sectors, or geographies), the adoption of common data standards is necessary. Open data standards and ontologies provide a reference point that enables two parties to share data and information in a way that ensures understanding is preserved and the meaning can be conveyed.
      58) To that end organisations should adopt international open data standards and ontologies when providing an API in order to ensure maximum interoperability.
      59) For more detailed information on appropriate data standards please see Appendix D.

    • API Governance

      60) Business failures have often arisen as a result of the lack of adequate technology-related procedures, including, for example, lack of security measures, systems development methodologies, limited system penetration testing for operating a robust business, and lack of technical leadership and management. The FSRA has therefore included specific Guidance regarding expected controls and processes to help mitigate these issues.

      • Version control

        61) Versioning and change control is very important and needs to be managed effectively. As such, organisations should have formalised policies and procedures in respect of the following where relevant:
        -   release numbers for all major and minor releases
        -   backwards compatibility for all API changes
        -   support for technology developers for major API versions for a specified period
        -   escalation path for when vulnerabilities come to light
        -   make a new endpoint available for significant changes
        62) If, however, for some reason the change is not backwards compatible, then the organisation must consider:
           •   Incrementing a version number in the URL (start with /v1/ and increment with whole numbers).
           •   Supporting both old and new endpoints in parallel for a suitable time period before discontinuing the old one.

      • Depreciation policies

        63) Clear API depreciation policies should be in place so old client applications are not unnecessarily supported.
        64) The time by which users/consumers have to upgrade, and how they will be notified of these deadlines should be clearly stated.