IOM3 – System Integration Standard

IOMG Technical Standard: IOM3 – System Integration Standard 

With the adoption of the  principles specified in the Application Programming Interface (API) Integration Standard, the Isle of Man Government needs to quantify this delivery through the use of the following standards.

This IOM3 document is a combination of the following three standard documents:

• Standardised Communication interfaces delivered through Restful Application Program Interfaces (API's)
• Standardised security rules for System Communication using RESTful Application Programming Interfaces (API)
• Transactional Communication standards using RESTful Application Programming Interfaces (API)

Standardised Communication interfaces delivered through Restful Application Program Interfaces (API's)

RESTful API – HTTP Verbs

Follow the industry standard and where appropriate build APIs that are RESTful, which use HTTP verbs appropriately to request and manipulate data.

When making requests, you should use HTTP verbs for their specified purpose. As generally understood, the following HTTP verbs are to be considered as follows when designing REST APIs

GET 

Use the GET verb for an API method that returns a version of the resource identified by the API url e.g.
GET /employer/ABC12-123
Expected return would be the employer resource with the Unique Identifier of ABC12-123

{

       "id": "ABC12 - 123",

"name": "REST Services Limited",

       "email": "info@rest.im"

}

POST 

Use the POST verb to create a given resource
POST /employer

The body of the message would contain the resource detail

{

"name": "Sample Services Limited",

       "email": "info@sample.im"

}

PUT 

Use the PUT verb to make complete changes to an existing resource
PUT /employer/ ABC12 - 321
The body of the message would contain a complete definition of the resource detail:

{

"name": "Sample Services PLC",

       "email": "info@sample.im"

}

 

PATCH 

Use the PATCH verb to make partial changes to an existing resource
PATCH /employer/ABC12 - 321
The body of the message would contain only changing elements of the resource:

{

       "email": "media@sample.im"

}

DELETE — For deleting a resource

Versioning

At present, it is expected for each API to be versioned through the URI path using semantic versioning.

The version placement can be anywhere after the service root, e.g.

• https://your.service/v1.0/api/function/
• https://your.service/api/v1.0/function/
• https://your.service/api/function/v1.0

This allows for multiple versions of the API to exist at a given time, therefore allow the potential for existing subscribers to keep subscribing for a period of time to allow for appropriate changes to be implement to use the latest version.

Of course, API's that implement side-by-side execution in this fashion must not have more than three versions operational at any one time.

It is expected that deprecation processes and policies are in place for API versions that are no longer operational or viable. Notification of approaching deadlines of a specific version should be communicated via the API documentation and announcements via the Warning header in the response.

Auditing

Auditing transactions of a personal or sensitive data is expected.  Logging of the date, time and by whom made the request will aid the organisation in responding to data access requests and to identify and resolve potential data misuse

API Management

The Isle of Man Government will provide an API management facility for the purposes of:

• Discoverability
• Documentation
• Billing
• Authentication

Discoverability

The API will be searchable and accessible via the API Management tool. 

Documentation

Use the OpenAPI Specification for the generation of the API documentation.  Documentation must include:

• Code samples
• Details relating to how development staff can use the API, e.g. expected parameters, request and response body examples

• Supported authentication methods
• Versioning information
• Availability, latency, ownership, deprecation policies and status capability

Backwards compatibility considerations

Billing

At present, the Isle of Man Government is not monetising it's API's.  However, if API's are to be exposed externally, then it is not beyond the scope of possibility that billing may be considered.

Authentication

The purpose of the API should determine the level of security to be enforced in relation to access. For instance, an API that handles sensitive data such as medical data, may require authentication – especially if there is a requirement to access the API outside of the scope of the API gateway. In this example, it is preferred for the API use an open standard such as OAUTH2 or OpenID

If access to the API is facilitated through the API gateway only (see IP Whitelisting) then the API may not require additional authentication. 

Standardised security rules for System Communication using RESTful Application Programming Interfaces (API)

In order to become API native, the Isle of Man Government needs to ensure that the correct level of security is implemented and adhered to by all parties.

As larger, monolithic systems are expected to be redesigned and remodelled into smaller, discreet pieces of functionality, there is the potential to introduce security issues and flaws. 

API security should be based on both Authentication and Authorisation in that:

• Authentication – To determine the identity of an end user. It is expected that open standards such as OAuth2 and OpenID are used as opposed to basic authentication.
• Authorisation – To determine the resources an authenticated user can access. An API should not allow user access to API functions that are outside the user's remit.  For instance, if a user had read-only access to a given API, the user should not be able to create, update or delete data. 

Authentication

Both internal and externally facing API's will be managed by an API Gateway or Enterprise Service Bus (ESB).  The API gateway will enforce security and access control as part of its remit.  Please refer to the Standardised Communication interfaces delivered through Restful Application Program Interfaces (API's) document for further detail relating to expected authentication standards

IP Whitelisting

It is mandated that all API's either managed by an API Gateway or ESB will ensure that they are accessible via the API Gateway or ESB only.  All requests from other routes must not be processed.  By configuring the API to whitelist the IP addresses of either the API Gateway or ESB ensures that the API only accepts traffic from these locations.

HTTPS

Whilst every effort is made to make the Isle of Government networks secure, the supplier should not assume anything when it comes to securing their endpoints.

Using HTTPS will secure connections to the API and encrypts and authenticates transmitted data, including that sent via web API. This also reduces the risk of "man in the middle" attacks by preventing the message content from being visible in plain test if intercepted.

Use Transport Layer Security (TLS) v1.2 or greater.

Authorisation

It is the responsibility of the API host system to determine what resources a given authenticated user has access to. Levels of authorisation should be detailed in the API documentation – see Standardised Communication interfaces delivered through Restful Application Program Interfaces (API's)

Security Considerations

There are a number of security considerations that need to be given, dependent on the API function.  The following list is a guide to what security aspects need to be factored throughout the API lifecycle:

• Input Validation – Enforce strict schema checks to prevent injection attacks
• Rate Limiting & Throttling – Protect against DoS attacks
• Token Management – Use secure token storage and rotation; prefer JWT
• Vulnerability Management – Perform regular scans and patch dependencies
• Secure Coding Practices – Follow OWASP API Security Top 10
• Penetration Testing – Conduct before go-live
• Immutable Audit Logs – Retain per compliance requirements
• Incident Response – Define escalation and recovery procedures

 

Transactional Communication standards using RESTful Application Programming Interfaces (API)

Due to the variety of systems and associated data, the Isle of Man Government will not implement a standard message schema across the organisation.  Implementing a standard message schema is too prescriptive and could be construed as a potential security risk in relation to mimicking requests.

That said, there are several standards that suppliers need to adhere to when developing API's

Data Formats

RESTful Endpoints ought to be able to consume and expose data as JSON or XML. Any other formats may be considered as acceptable – however, not at the expense of consuming systems needing to have additional modules, development or configuration in order to subscribe to the API's

In the case of communicating with legacy systems, it will be role and responsibility of the Isle of Man Government's Integration platform to broker and transform messages between the subscriber and publisher.  This transformation must not take place within either subscribing or publishing systems – this leads to tight coupling and unwanted dependency.

UTF8

Use the Unicode Transformation Format (UTF-8) when encoding text or other textual representations of data.

Date and Time

The Isle of Man Government requires the ISO 8601 standard to be used to represent date and time in both requests and responses. This reduces the need for transformation between publisher and subscriber and reduces the scope of errors regarding data misrepresentation.

e.g.

                Date only format – yyyy-MM-dd e.g. 2019-05-13

                Date and time format - yyyy-MM-ddTHH:mm:ssZ e.g. 2019-05-13T15:45:30Z.

Responses

Only respond with the information that is being requested.  For instance, the response should only return specific and relevant information, with no more detail than is requested.  There is an expectation for the client application to handle the response accordingly.

E.g. If a request is being sent to check whether an individual has a driving licence:

{
"HasDrivingLicence":true
}

As opposed to

{"Individual":{

        "Forenames":"John Peter",

        "Surname":"Doe",

        "HasDrivingLicence":false,

        "DateOfBirth":"1969-06-13",

        "VehicleRegistration":"MAN-123-YY",

        "RegisteredPostcode":"IMX 9XX",

        "HouseNumber":"129"

}}