API First: Also in systems engineering?
Many concepts from software development often appear with a time delay in systems engineering. For example, software developers have been using clean versioning (CVS, Subversion, git) for a long time, whereas this is still far from being the case everywhere in product development. Or concepts such as test-first and behavior-driven development, which are applicable and useful in systems engineering in principle, but are still rarely found there today.
Today we are talking about API First, an approach. The focus here is on the API, the interface. API First is not yet really widespread in software development. Nevertheless, it is already worth taking a closer look and examining its applicability in systems engineering.
API First means interfaces as first-class elements
Programming interfaces (Application Programming Interface, API) have been around for a long time. These enable modular software. In some situations, these are also defined very carefully. This is particularly the case when the interface is public. The architect normally has the task of dealing with the interfaces of a system. Unfortunately, APIs all too often "grow" and are not properly documented and tested, which can lead to problems and frustration.
Too often, interfaces - including APIs - grow organically
The idea behind API First means that interfaces receive the same attention as the code: Developers must not simply program away, but must plan, maintain and test the API properly.
Furthermore, the developer or architect defines the interfaces at an early stage. In the test-driven development this is even necessary. After all, a test can only be formulated if the interface is known, even if the implementation is missing.
Equally important is the aspect of verification, preferably combined with automation. Here we find Design by contractan approach in which the behavior of the interface is specified with a formal description. For example, we could use it to specify that a function for calculation does not process negative numbers, even if the data type of the parameter allows negative numbers.
3 Principles of API First
The following three principles are the basis for API First software development:
- The API is the first user interface (UI) to be developed. Here we assume that a user interface designed for humans is also based on the API. Therefore, the first "customer" of an API will be the developer of the user interface (UI). This decouples the UI from the application. This means, for example, that an application can easily have several user interfaces (and machine users) that are all operated with the same API. As soon as the API makes a new function visible, it is also available in all UIs (with a good architecture). Even without a user interface, people can interact with the API, for example with interfaces such as Swagger.
- The implementation can change at any time without changing the API. We are already familiar with this concept from systems engineering, for example through Black box specifications. Here it is important that developers do not cross interface boundaries with implementation details. This concept also makes the use of Mocking for testing.
- The API is comprehensibly documented, or self-describing. The API must be understandable for the consumers of the API, even if they were not involved in the creation of the API. This includes, for example, using descriptive identifiers for parameters and function names. As mentioned above, this can also be refined using machine-readable contracts. Interfaces such as Swagger make this information visible and guide developers who want to utilize the API.
Advantages
This development approach makes it much easier to exchange components and develop the application quickly without affecting other teams (as long as the API only changes slowly or not at all). Teams can work well in parallel. We can also use it to Complexity because this can be hidden behind the interface. All of this reduces costs and increases the speed of development.
Interfaces First in Systems Engineering
The concepts described here can also be applied in systems engineering. The major challenge is that Interfaces in the SE There is not the same homogeneity as in software development. With regard to software, there is often only one interface technology, whereas in SE we have to deal with interfaces for data, forces, media and much more. The SysML tries with formally specified Blocks and ports to master this challenge. To do so, however, an organization must first overcome the hurdle of introducing SysML, at least at the architectural level.
There are a number of alternatives to SysML, but we should never commit ourselves to one language/notation. The real challenge is the mindset, i.e. realizing an interface-first mindset in the team.
Photo by James Lewis on Unsplash
