Skip to main content

API Principles and Patterns

The API first pattern is where the APIs of a system are treated as a first class citizen of a software product. The API interfaces represent the logic of how a solution is implemented instead of just the code. This approach places more than the user of the product at the centre, but also facilitates system integration from the ground up, planning for and ensuring that up or downstream system users can avail of the same functionality. There are significant benefits for development teams and product consumers.

  • Dev Teams can work in parallel / coding against interfaces instead of build time dependencies.
  • Increase the velocity of releasing new functionality and features.
  • Reduces the risk of errors or cascading errors.

The implementation of CQRS (Command Query Responsibility Separation) means that API consumers are presented with one interface for performing updates to data (command) and a different interface for reading back (query) data. When exploring our APIs you will see that the majority of functionality is offered this way. This pattern complements the architectural choices made by fenergo in creating the SaaS product. We are using event-sourcing to store data as events in an append-only log and then process them in order of arrival. This introduces the concept of "eventual consistency" for incoming data but has the benefit of high performance in terms of response times and better still, allows for tremendous scalability. Learn more about Event Sourcing here

Across the SaaS product, a Domain Driven Design approach has been taken with functional areas and reflected in the API interfaces. More Info. Each Domain takes responsibility ONLY for the implementation of functionality inside that Domain. They then interact with each other via well defined interfaces. You will encounter the Domains within the API Catalogue with regard to how the APIs have been named.

All of the APIs on the Fenergo SaaS platform are REST APIs. A REST API ( also known as RESTFul API - representational state transfer) conforms to the REST constraints and when consumers use these APIs they do so using the HTTP methods: GET, PUT, POST, DELETE which offer the ability to read, update, create and delete resources. All data exchanged on the fenergo platform is done using JSON objects and there are a number of key advantages to this.

  • JSON is easier to read than XML equivalents and also consumes less bandwidth.
  • The HTTP methods are universally standard, and offer maximum compatibility for consumers without prescribing any specific client technology.
  • A resource (such as client record or some contextual business object) is made available at a URL, and then via the HTTP methods, a client can interact with that resource. This common way of interacting with REST APIs is universally best practice and softens the learning curve for consumers.
  • All state can be managed at the client side of the interaction and every REST call is stateless.
  • Standard HTTP response and error codes can be used to determine the outcome of method calls.

Modern applications have evolved to extend beyond the traditional protected domains of corporate networks or trusted devices. This requires fit for purpose Authentication mechanisms to secure APIs. Fenergo uses "Duende Identity Server (Enterprise Edition)", which is an OpenID Connect and OAuth 2.0 framework to provide Authentication services to UI Users and API clients. Click here to learn more about Duende Identity Server. We have implemented industry best practice to secure the APIs and clients can utilise API Scope Patterns, Client Credentials and MTLS to protect and govern access to the APIs. Username and Password Authentication is not supported as it requires the credentials to traverse the network for EVERY call. Instead the Credentials are used to create an access token which is valid for a short period of time and then expires.

To facilitate the integrations clients want to build, fenergo supports two types of Notifications. Notifications are messages which clients can reach out and grab or listen for. They indicate that an Event has occurred on the platform which might be of interest. These notifications can be used as a trigger to implement additional logic in other systems or automate steps within a clients broader technical landscape.

There are two types of Notifications which clients can select to work with, depending on the use case being solved for. Each has their own advantages. The main difference is who is responsible for delivering the notification, Client to grab or FenX to push.

  • Polling - Where Notifications are stored in batches as events occur and clients can call into FenX and retrieve them.
  • Webhooks - Where Notifications are pushed in real-time by FenX as events occur to a client designated endpoint.

The Fenergo SaaS product is Cloud Native and we have selected AWS as our cloud platform vendor based on features, functionality and global availability. Cloud Native also speaks to the best fit technology choices we have made which make up the platform. Services like AWS Lambda and DynamoDB which allow us to deliver and scale a product that can meet the commitments we make to our clients.