API-Basics for Digital Signage

The second part of our series about interfaces in Digital Signage highlights technical aspects of interfaces. invidis reports in cooperation with Florian Bogeschdorfer from DS Connekt about interfaces, missing standards and the correct API design. Soon we will answer what makes a good API. But before we get there, a few basic technical aspects.

API architecture

In this article we want to limit ourselves to networkable APIs – others don’t make sense in DooH / DS except for special cases. Therefore, the architectural decision is easier. The candidates for your API are:

• SOAP (Simple Object Access Protocol)
• REST („Representational State Transfer“)
• RPC (Remote Procedure Call)
• HATEOAS („Hypertext as the engine of application state“)

Since this article is primarily not aimed at developers, let’s just have a very brief look at those API architectures:

SOAP is very complex and versatile but is mostly used only within shared infrastructures and requires more storage, performance, and traffic because of its structure.

REST is the most common interface technology that has its power in the exchange of data and is very „lean“ and easy to learn.

RPC is more capable of triggering actions and provides executable procedures for doing so.

HATEOAS includes the ability to include the description and the user interface with the API – the supreme discipline. A correct HATEOAS implementation makes it possible to make changes to the API without having to reprogram the clients. HATEOAS is the highest level of a REST implementation.

You could offer a data exchange interface via REST, react event-controlled by means of RPC and realize user interfaces via HATEOAS.

All four technologies have advantages and disadvantages, some developers even merge them happily and maybe you should have multiple APIs and different technologies anyway. There are of course more architectures / styles / technologies used in API development which we won’t cover here.

A good API – finally

What is a good API? The answer is quite simple: a good API is one that can be sold well. After all, an API is always a product from an entrepreneurial point of view. Nowadays users (customers!) have the choice between many APIs and often the quality of an API decides which product is used.

Improve the chances of your API by developing the API according to the following guidelines:

• follow the outside-in or contract-first approach
• your target audience are developers, because they have to deal with the API
• provide easy access to useful features
• carefully integrate the API into the software universe of your company
• design the API in an iterative design process
• the API is stringent and comprehensible
• it complies with standards wherever possible
• it is safe
• it is neatly documented
• it is maintained regularly

Behind each of these points are a lot of other terms and expertise – to address all of them I lack the space here and you the patience, but I would like to highlight two points:

The outside-in approach vs. Inside-Out and Contract-First

In the inside-out approach, the manufacturer looks at his functionality, abstracts it more or less and develops an API for it. These APIs can usually be programmed quickly and cheaply but are too much based on existing structures and may fail on the market. At a minimum, you should consult an expert who can provide functionality and API design and define critical specifications from a different perspective.

The opposite is the outside-in approach, which first analyses what your customers want, analyses projects and their requirements for APIs and whether you can meet them. The great advantage is that these APIs are oriented directly to your customers’ requirements and the design is also customer-oriented and therefore easy to use. On the other hand, there is an increased effort in connecting the API to your backend.

The contract-first approach is fine – here you have a contract with a customer who specifically shares his needs and may still be paying for the programming. If you can add some market research and abstract well, then you may be able to get a good API and instant recapitalization. But beware of the custom feature trap: we’re not talking about custom feature development, but about developing an API that should be available to many. If you do not keep track of that, you’ll end up with multiple, similar APIs and the associated disadvantages.

API design

API Design consists of the following steps that build on each other:

• analysis (needs, integration, costs)
• architectural decision-making
• frontend design
• prototyping
• implementation
• publication
• maintenance

Using an API description language like openAPI / Swagger or RAML iterative / agile approaches can be realized, which can show weaknesses even before the actual programming and during the development. You can have the API, the backend implementation, and the API clients programmed at the same time – even by different teams – and before the API is completed, which can significantly reduce the time to market.

Moreover, such an API description language also takes care of most of the documentation and provides the review of design decisions without further programming.

Personally, I think that an API description language should not be waived. Currently, openAPI is the way to go and coming up more and more in recent tenders – so try to design your interfaces with this language.

What you can do with an API

First and foremost, you will create APIs to exchange data with customers. For example, your customer could send playlists directly from SAP or read out the playbacks of the individual spots for invoicing. Every customer has different requirements, but a clever API can cover them all.

Even user interfaces can be easily connected via API. With the API you simply abstract the functionality of your backend and now you can develop customized user interfaces at any time without having to adjust code in your backend.

Successful companies such as Amazon also use APIs within their own company – so they are always prepared for future requirements. In your case it could e.g. be that a customer needs 2000 Windows licenses but also has 5000 Arduinos in use. If your API is neatly written between backend and player (yes, you probably already have one!) then it’s easy to connect the simpler features of the Arduino player via API (or other SoCs, Raspberry, …).

Even a player itself may have an API that allows other devices to access using the intranet. Maybe a device with RS232 interface, which is located 150m away? No problem – RS232 to REST converters for less than 100 EUR make it possible and suddenly the device connects via API with your player – for example to communicate a fluid level or other process metrics. A sensor controls the content according to the outside temperature, a screen changes its content when a tray is set down and a POS system transmits current prices.

Using APIs you can realize the most amazing projects. Projects that are innovative and really fun. Or just make money.

Globalization, consolidation, specialization, multi-channel, marketing, personalization – without APIs, you will not be able to realize much in the future and you will not be able to explain to your customers why he / she should not use the software provided with the screen.

The API train is in motion, jump on before it leaves the station!