With Piclo’s spread across the globe, robust solutions focused on scalability are more important than ever. Our recent aim at Piclo has been to find a generic approach to our internationalisation (i18n) processes that enable quick vertical expansion via configuration - avoiding (as much as possible) any locale-specific business logic. Meanwhile, the number of integrations between Piclo’s and partner’s APIs is also growing. So how have we chosen to approach this dual scalability problem?
Striking the right balance
When designing our APIs, we had to strike the right balance between cross-locale consistency and regional particularities. Django already offers a plethora of i18n features, including lazy string translation for API responses and Django templates alike. While these tools are powerful, our ultimate decision was to avoid any translation for API payloads across locales. We did not want a different set of APIs per locale, adding unnecessary complexity to the codebase and ironically costing us the ability to scale effectively.
What we wanted to achieve was to have APIs that were:
- Time zone-aware
- Aware of location specific energy industry variations
- Continuing to use English key/value pairs in JSON payloads
- Continuing to use English in responses and error messages
- Consistent with concepts defined in the UK APIs
Cross-locale Data
Data consistency is important to us. To ensure data relationships and the way Piclo represents energy industry concepts do not change, we avoided any changes to our underlying data models. However, different locales have varying designs and needs. For example in the United States, where we have launched an international partnership with National Grid, the connection voltages for assets are different to the UK. Without changing the underlying models how could we handle this?
How did we tackle it?
Piclo Flex APIs are designed with a Model-View-Controller (MVC) architectural pattern in mind. At Piclo we use Django Rest Framework (DRF) to achieve this. DRF provides us with all the well-maintained and industry-proven tools we need to design our APIs in a way that is easily maintainable, scalable and secure. It has provided us with a framework that has allowed us to flexibly extend and append the core functionality to our specific needs, such as custom i18n, while also significantly reducing development time.
APIs built using Django Rest Framework (DRF) consist of several layers; handling data all the way from the database to the URL. In the context of Piclo Flex APIs, the crux of the business logic can be found in the ‘view’ and ‘serialiser’ classes. In Piclo Flex there are a great number of views and serializers, working together to create our API user journey.
To ensure consistent API i18n across our codebase, we needed our solution to be:
- Generic enough to be used by any ‘view’ in Piclo
- Designed to abstract the complexity of locale-based decisions away from the view
- Easy to use and maintain
- Prescriptive enough to ensure consistent use
- Reusable by all engineers across Piclo
With those in consideration, we decided to write a bespoke mixin class to be inherited by our class-based views. Dubbed ‘RegionalViewsetMixin’, the mixin dynamically identifies and handles the likes of locale-based requirements, ensuring serialisation and user permissions are in line with that region. This helped us to avoid piling layers of regional complexity within our views and kept our code aligned to Object Oriented Development principles.
To ensure reusability across all our services and teams, we added this to our Piclo utilities package – an internal library where all of Piclo’s engineers collaborate and share code. So now if an engineer wants to i18n a new API endpoint, or just update an existing one, all they need to do is to inherit this mixin and set up some basic configuration. By defining this locale-specific configuration for a specific locale, we can get our new API up and running in multiple locales in no time! This has been a great success, allowing cross-team alignment and collaboration on a streamlined approach to APIs and API i18n.
What about API Specifications?
At Piclo we use Redoc as a way to serve up our API specifications. While Redoc provides great features ‘out of the box’, a little customisation was required to enable i18n. Simply put, we needed to flag parts of our specs that were meant for certain locales only, or might vary per locale. Piclo’s use of OpenAPI 3.0 format to define specifications in conjunction with a little bit of supporting Javascript to service our API documentation, lended itself neatly to a solution.
By adding a custom flag to sections of the OpenAPI definitions, we were able to specify what region they should be displayed in. The flag is parsed by some simple Javascript code and then compared with the domain name, removing unnecessary parts of the documentation. For example, all things marked PRT (Portugal) would be removed for UK documentation. Once again, Piclo engineers have full control of what specifications show and where with a quick and easy flag!
So, did we do it? Are we unlocking the full potential of automation internationally?
With these in place, we provide an important piece of the jigsaw for unlocking the automated energy market across the globe. In combination with our internationalised frontend and infrastructure, Piclo can now set up in new countries and continents scalably and swiftly, providing the full range of benefits of energy industry automation.
Want to know more about i18n of a B2B product? Read my colleague Matthew’s blog on Internationalising a B2B software product!
