How to open API following protocols
It’s quite common to create a custom API when starting a business. It’s hard to identify the patterns of how our features could be used by third parties. The same thing happens to the entire market. Standards are created (or at least they should be) based on the experience, once enough parties are interested in using the same language.
If you work in the energy market (both traditional and mobile), finance, or any other well-established area, it’s likely that there are already some standards describing what your business does.
But when you are launching a startup, who cares about standards? When you’re following the LEAN approach, fulfilling standard protocols isn’t the most important thing at the beginning.
But if you succeed, there is a chance you will want to open your API. And if yes, you will want to sell it to many customers. If you answered yes twice, it’s the right moment to onboard the API standards into your system.
Compare your model with the model described by the standard
Whether you want to introduce a new e-commerce platform, an electric vehicle charge point network, or a payment platform, there are some concepts that are common for all systems, no matter the vendor. It’s common to have checkout in an online store, charging session in an electric vehicle charging network, and some way of money transfer in a payment platform.
So there is a big chance that your model will fit more or less to the model from the protocol you’d like to implement. But every component has its essential parts and some additions. It’s always good to check upfront if your model matches the standard, at least in these essential parts. A good practice is filling a lookup table with all of the parameters from the standard and related parameters from our model. It’s smart to make such a table upfront. It’s work that needs to be done anyway, but it’s much cheaper to do it before writing the first line of code.
If you create something special, protocol designers may not foresee it. It doesn’t mean that the standard is not for you. If you use an extensible data format, like JSON, you can make some changes and still comply with the standard. API clients may use the standard form, but you can still give them access to your cutting-edge feature. What’s more, potential clients who already have the standard implemented will require much less effort to use your additional feature than if everything would have to be prepared from scratch.
Check if you need to implement all or nothing
It’s good if the standard has some parts that can be introduced independently. There may be some common parts, like everything related to the security and other non-functional parts. But core components don’t have to depend on each other. Let’s take a look at some examples. The OCPI ( open roaming protocol for electric vehicles) standard has few non-functional modules:
- Versions
- Credentials
And a few more core components:
- Sessions
- Tokens
- CDRs (charging records)
- Locations (charging points)
You need to have Version and Credentials to start working with OCPI. But you can expose Locations without providing Sessions, Tokens, or CDRs. This is a great advantage of this protocol. With a relatively small effort, you can start talking to your partners using OCPI, even if you don’t have some other concepts covered by the standard.
Choose the correct version
Like many other things that have strict definitions, standards are versioned. Every developer knows that it’s good to carry out security updates, use the latest versions of libraries, etc. It’s a bit different from standards. If your goal is to open your API to as many clients as possible, you probably can’t just go with the latest version. It’s good to invest some time and do the research upfront.
Standards are maintained by an organization or company/companies. But it’s common for communities to drive changes in the protocol. You can try to join the community before you decide which versions you’re going to support. The community is usually well-informed and knows that, for instance, almost no one is going to implement the current version because everyone is waiting for a breakthrough change in the next version, and the previous one is used by most big players.
Think about the architecture
If you have a microservice architecture implemented, there are some patterns you will probably need when introducing the standard into your ecosystem so that it’s not mixed with the existing core components. These are:
- API composition
- API gateway
As your application is probably divided into components based on your domain, you will need to query multiple services to prepare the response. This is where the API composition pattern comes into play.
The second thing worth considering is where to put the code, which serves as the entry point of your implementation of the standard. Separate component for such a thing sounds like a good solution, but it really depends on your system, and maybe implementing it as a part of existing API gateway is good enough.
Summary
Introducing a standard API to expose features that were initially developed only for internal needs may be a challenging task. The most important thing is to gather as much information as possible upfront to address bigger changes earlier.
In a pessimistic scenario, you will need to put the protocol you choose away and look for something different. But it’s still much better than doing the same thing after spending weeks on coding. As standards are not something we can change easily, we need to pay attention and choose the right protocol with the right version.