Search Background

Get instant support with our search!

MetaCompliance – Customer API Design Specification

User Avatar
Enya McManus

Updated

Requirements Analysis 

The requirements analysis for the MyCompliance Cloud Customer API can be viewed from several perspectives. We will define a set of security, usage, functional, and technical requirements for the API.

Hosting Platform 

MyCompliance Cloud is hosted on Microsoft Azure, with APIs built as API Apps on the Azure App Service. This architecture provides scalability and security as core features.

The Customer API is built on App Service and uses Azure API Management to provide enhanced security and greater flexibility in managing the API. Within this service, several key features are available:

  • Product Sets – Policy-based products that govern customer usage of the API.
  • XML-Based Policies – Enable granular control over API calls and product configurations.
  • Developer Portal – A portal that allows customers to explore the API and review available calls.

Security Requirements

Security of the MyCompliance Cloud Customer API is the most critical requirement when designing an API that is accessible to customers. Security is enforced through features provided by Azure API Management (front end) and by the API design itself (back end):

  1. Subscription ID
    All customers require a subscription ID to access the API. This ID is provided when customers sign up to use the API.
  2. HTTPS and IP Restrictions
    The API can only be accessed using HTTPS and from defined customer IP addresses. This requirement is enforced through policy configuration.
  3. GUID Validation
    Each API call must include a GUID defined by MetaCompliance. If this GUID is missing, the call will fail.
  4. TLS Enforcement
    Only TLS 1.2 is allowed. The default cipher suites of Azure App Service and API Management are used.

Usage Requirements 

Usage of the API will be governed by a defined set of Products within the API Management service. 
Products can be thought of as a set of limits on how a customer can use the API. The following Products 
are proposed: 

1. Small

  • Access to all APIs
  • Rate limits:
    • 1 method call every 2 minutes
    • 30 method calls per hour
    • Maximum 250 calls per day

2. Medium

  • Access to all APIs
  • Rate limits:
    • 1 method call per minute
    • 60 method calls per hour
    • Maximum 500 calls per day

3. Large

  • Access to all APIs
  • Rate limits:
    • 2 method calls per minute
    • 120 method calls per hour
    • Maximum 1,000 calls per day

Functional Requirements 

The MyCompliance Cloud Customer API requires a defined subset of APIs that can be called independently and are not dependent on each other. This aligns with the modular nature of the MyCompliance Cloud platform, as utilised by our customers.

1. Error Handling and Data Validation

  • Any call that does not include the GUID (as defined in the Security Requirements) will fail and return:

    400 Bad Request
Message: "Bad key data"
  • Application Telemetry is written to Azure Application Insights as follows:
    1. Log an event for the API call with the declared GUID.
    2. On error, log the error to Application Insights with the declared GUID.
    3. Return a 400 Bad Request to the customer, indicating that an exception occurred.

2. Main API

  • GetCompanyUsage – Retrieves overall usage data for the customer.

3. Compliance API

Used by customers who have the Compliance module in MyCompliance:

  • AddContentResults – Allows customers to display policy content on their own systems and send responses back to MyCompliance.
  • GetAllContent – Retrieves all compliance content for a customer.
  • GetPolicyResults – Retrieves all results for an individual policy.
  • GetSurveyResults – Retrieves all results for an individual survey.
  • GetUserPolicyResult – Retrieves all results for a user for an individual policy (can be used with GetAllContent to find the correct policy).
  • GetUserSurveyResult – Retrieves all results for a user for an individual survey (can be used with GetAllContent to find the correct survey).
  • GetUserResults – Retrieves all compliance results for an individual user.

4. Learning API

Used by customers who have the Learning module in MyCompliance:

  • AddContentResults – Allows customers to display Nano content on their own systems and send completions back to MyCompliance.
  • GetAllContent – Retrieves all Nano content for a customer.
  • GetAllCourses – Retrieves all courses for a customer.
  • GetCourseResults – Retrieves all results for an individual course.
  • GetUserCourseResult – Retrieves all results for a user for an individual course (can be used with GetAllCourses to find the correct course).
  • GetUserResults – Retrieves all course results for an individual user.

5. Phish API

Used by customers who have the Phishing module in MyCompliance:

  • GetAllContent – Retrieves all phishing content for a customer.
  • GetPhishResults – Retrieves all results for an individual phishing simulation.
  • GetUserPhishResult – Retrieves all results for a user for an individual phishing simulation (can be used with GetAllContent to find the correct simulation).
  • GetUserResults – Retrieves phishing simulation results for an individual user.
Back to all articles