A RESTful API

Aside of all technical details in the space of Application Programming Interfaces (API) it is made to make content available. The VOIS Server API follows the basic principles of the web: a resource is uniquely addressable with a path. VOIS follows international standards as much as possible to reach a high compatibility with its environment.

Every module get an own so called “context path”. Per example a particular identity would be addressed under “/identities/2e52010f-7aa0-4a1f-851a-438304c91683”.

The API gateway organizes three types of paths:

• module specific paths e.g. /news
• utility paths e.g. /maps or /addresses
• internal paths e.g. /users

Formats

The VOIS standard data format is JSON. It fits perfect into the needs of software clients connected over a HTTP network. If the client is another server the preferred format is often XML. And last-but-not-least users often ask for CSV formatted list to being able to import it easily into a spreadsheet. The API gateway offers a way for software clients to decide in which format the response from the VOIS server should be.
 

Policies

Similar to the fine-granular access control list for user accounts the API gateway manages connections to software clients and other servers. Every configuration is identified by a so called API key. The term is a little bit misleading (but widely used) – it’s a username not a secret.

The following list is a subset of configurable parameters:

• IP-Filtering
• JWS/JWT
• Latency
• OAuth2
• Rate Limiting/Throttling
• Request Content Limit
• Request Validation
• Resource Filtering
• CORS

Many of these parameter are security related. Some others enabling compatibility for external systems.
But one of the most interesting use cases is to monetize the API usage on top of these configurations – more about that is described in the following section “Plans”.
 

Reporters & Analytics

Response time, response status (errors/successes), payload size and a lot more metrics are collected to analyse the behaviour of the API and how it is consumed. These metrics are focused on technical aspects and measure the hosting success. This data is crucial for contracting with partners (e.g. banks) and monetizing the data behind the API. In such a relationship the reporters are used to deliver metrics into specific foreign storages by actively calling other dedicated APIs. Similar to policies the analytic capabilities are a foundation for monetize on top of the API (see “Plans” for more information).

Plans

Partners can subscribe to the VOIS API and obtain an individual API key. The shown plan above are example configurations. The starter and professional plans have a two-step subscription workflow configured. An authorized persons needs to finalize these subscriptions in the API management dashboard. The documentation section of the portal would enable developers to understand the API and implement software against it. Additionally information like Health check endpoint and Fail-Over handling is described.

In summary these tools enable every VOIS server host to establish post-paid and pre-paid plans with all necessary aspects for professional software service contracting.