What to look out for when developing APIs
Whether exchanging data from system to system or with customers and service providers, enriching artificial intelligence with data or analyzing and optimizing processes: interfaces / APIs are the backbone of digital structures and processes – not only in the company, but in the entire digital world. However, in order for interfaces to fulfill their intended application scenario, a few basic principles must be observed.
First of all, it is important to understand which systems are involved in the desired data exchange. This is because it is usually not just a matter of two systems communicating with each other, but also involves various middleware or other stations on the way to and from the respective interface partner. The question therefore arises as to whether all the systems involved can communicate with each other at all or whether additional components may be required. A common example in the field of web services is the “translation” of the network protocol SOAP (Simple Object Access Protocol) into the REST format (Representional State Transfer). Tools such as Orchestra are ideal for carrying out such conversions.
Another key aspect is the security of the interface. The exchange of special certificates forms the basic security. In addition, the use of various authentication options, such as the token-based Oauth and Oauth 2.0 methods or credential-based methods such as Basic, is a good option. However, security is not just a matter for the infrastructure; software architects and software developers also need to be briefed in this regard. It is worth taking a look at the ATT&CK (Adversarial Tactics, Techniques, and Common Knowledge) framework, which currently lists 14 categories that attackers use to achieve their goals. Examples include privilege escalation and command & control. If these are taken into account during the architecture and development of the interfaces, potential security gaps can be proactively closed in advance.
It is just as important to clearly define individual operations and the API mapping within the interface. Here it is important to determine which interface operations are actually necessary. It is also advisable to clarify further framework conditions with the respective interface partner. This is because it makes a difference whether a master-slave or a push-push interface is being developed, for example, and whether it is synchronous or asynchronous.
Security aspects also influence the interface design
The art of defining an interface is to proceed neither too coarsely nor too granularly – although this also depends on the type of interface: If, for example, assets are imported, it is sometimes sufficient to offer an interface action for creating and updating the assets. It is important to check in advance whether data actually needs to be deleted for the import. If data records are removed from the system accidentally or even as a result of a cyberattack, it often makes more sense to simply deactivate or archive the data.
This means that security aspects also influence the interface architecture. The more interface operations are permitted and the more open the APIs are designed, the more gateways they offer for potential attackers. Interface developers should therefore ask themselves: what data should be visible and what data should be changeable and when? Data worth protecting is another important aspect in this context. It is therefore advisable to make only the most necessary data accessible, true to the motto: as little as possible, as much as necessary. Any guidelines such as the ISO 27000 standard or the GDPR (General Data Protection Resolution) must always be kept in mind, especially with regard to customer data.
Of course, the interaction between API methods and API mapping also plays a fundamental role in interface design. A change in a ticket system, for example, serves as an illustrative example. A change is usually a linear process that should ideally run in phase synchronization with the respective interface partner. It is important to ensure that interface calls can only be made for the current phase of the change. This is because it can be fatal if, for example, the interface partner can change its own risk assessment or classification in this implementation phase – i.e. at a time when these values must already be fixed. One solution to this problem could be to reject the data or even the entire interface call with a clear error message.
Define the desired benefits of the API and draw up a cost/benefit analysis
All of the points mentioned above are important considerations with regard to interface design. It is important to never lose sight of the big picture and to always keep an eye on the context or use case and the desired benefits of the planned interface. Useful questions in this context are, for example: Are there any internal dependencies? Can employees use the interface to place orders for IT equipment or office supplies, for example? Who works with the interface? Are there external dependencies? Are customers offered more usability through chatbots, for example, or through self-service with subsequent ticket creation? Here too: Who works with the interface?
The above examples show that APIs can offer users a certain level of convenience and may also help the company to save money. However, the quantity structure also plays a role here and it is worth making a cost-benefit calculation in advance: Creating an elaborate interface for 20 users will rarely be worthwhile, whereas an interface for 200 users very probably is. A complete overview can often be obtained very well with the help of visualizations – for example in the form of a detailed plan that lists all components used, users and all other factors involved, quantifies quantities and weighs up costs. It is important to include not only the costs, but also the cost savings and the benefits of the API. A good interface can be a large investment, but one that pays for itself over time – whatever the goal.
Conclusion for your next interface project
In summary, it can be said that an interface project cannot be an ad hoc project, but requires sufficient time in each project phase to examine all current and future scenarios relating to the interface in order to ensure efficient, long-term and usable use in the respective application.
