Best practices for API development in e-governance projects

Best practices for API development in e-governance projects

Future of data exchange among departments to support integrated digital processes in a large ecosystem such as digital Canada shall reply on Application Programming Interface (API). APIs are one of the best mechanism existing today to support real time system interaction and data access in a controlled manner. Government has outlined standard practices to be followed while designing APIs. Many of these practices are already industry standards. The recommendation are stated as under:

“As for all application development, API development should also adhere to standard practices such as Open by default, prefer open standards and solution, design with customer in mind and iterate as per need.”

  • APIs must be RESTful by default
    • Uniform Resource Locators (URLs) should represent only resources (business object and  entities)
    • Data structure shall be represented in JSON based repersentation by default
    • Use URIs to identify response data
    • Use HTTP headers such as CONTENT TYPE, ACCEPT, AUTHORIZATION
  • A well defined message schema is a must
    • Prefer industry standard and platform agnostic information model such as NIEM, HL-7, HR-JSON etc.
    • APIs must abstract back end physical data representation and internal technical details from consumer
    • Conform to standard HTTP status code when building RESTful APIs.
    • All interaction through APIs must be stateless
  • While APIs are made with the intention of exposing data or services publicly, ensure APIs are first consumed within internal application wherever applicable.
  • Secure API: Based on the sensitivity level of data being exchanged, controls such as message level encryption, mutual authentication and digital signature may be applied. Following practices should be adhered:
    • Secure communication connection (TLS 1.2 and above) by default.
    • Build resiliency for common API attacks such as SQL injection and buffer overflow. Not to forget – validate before consuming data
    • Always authenticate and authorize before any operation using Open ID Connect and Open Authorization (OAuth 2.0) for RESTful APIs.
    • Prefer industry standard tokens such as JWT for authenticating RESTful APIs  with reasonable expiry duration.
    • Instead of simply white listing inbound IP addresses, use a secure gateway layer to provide a security control point
    • Any changes to API should be followed by security testing before production roll out.
    • Access to APIs dealing with sensitive data must be logged for future audit and reviewed regularly.
    • Track usage of APIs and monitor for suspicious and abnormal activities.
  • Consistent encoding and meta-data: Consistency in meta-data and encoding ensures inter-operability and easier maintenance. Recommended practices are:
    • Prefer Unicode Transformation Format-8 (UTF-8) for encoding all textual representation of data.
    • All API should represent consistent date and Timestamp  format.
    • Support all official languages
  • Manage API life cycle
    • Based on feedback, keep building API iteratively.
    • Every API must be version with URL reflecting only the latest version and support available to at least N-1 version.
    • Publish point of contact for supporting customer in all API consumption related matter.
    • Define and manage SLA (for example Service Availability, Support hours, Scheduled outages, Throughput Limit et al.) upfront for the API.
  • Measure and benchmark APIs
    • Integrate load testing and measurement performance thresholds with the development cycle.
    • Measure and publish performance benchmarks such as max stable throughput, average response time.
    • Monitor performance to identify trends and measure API capacity
    • Throttle against SLAs to guard against unexpected spikes.
  • Design APIs sensibly: APIs should be judiciously designed to ensure sustainable architecture
    • Prefer query based APIs (pull pattern) over data sink APIs (push pattern). Only bulk data integration techniques and tools should by used for data synchronization.
    • Restrict wildcard queries as they are resource intensive
    • APIs exposing large dataset must limit data through data segmentation predicates.
    • Prohibit use of consumer defined query on master and transaction data. It is prudent to identify valid query use cases in advance.
    • Considerations for bulk data transfer using API:
      • Restrict to smaller datasets in low overhead formats (CSV, JSON)
      • Allow API to prepare a file for download, and return the link for subsequent download
  • Publish and document the API
    • For the purpose of discovery and managing API life cycle, publish the APIs to API store
    • For RESTful APIs, use OpenAPI specification to generate human readable documentation.
    • Prefer Test Driven Development (TDD) methodology. Publish unit tests and test data.

Further Readings

Leave a Reply

Close Menu