CIRC4Life ICT Platform REST Web Services API

General

The ICT Platform REST Web Services are described as OpenAPI version 3 specifications. The OpenAPI Initiative is a joint effort of industry experts to standardize the method of describing REST APIs. The specification aims to clearly define data models and methods using general purpose formats: YAML and JSON. This approach allows developers and teams using different software stacks and technologies, to easily design and use REST servers and clients.

ICCS describes all ICT Platform REST APIs using YAML OpenAPI specification. The underlying technology stack is Java, but this is transparent and an internal implementation detail to anyone that wishes to consume the services. The OpenAPI YAML specification files listed in next section are the only knowledge required by developers of client applications. These specification can be used to generate all plumbing and connecting boilerplate source code required to communicate with the ICT Platform REST services. All data structures for serialization, networking and HTTP request/response transport can be generated using the OpenAPI Generator. The developer is required to fill in only the business logic that implements the handling of REST service responses and the creation or proper requests, all by using already generated classes for this purpose.

This document only describes the REST Web Service endpoints and their input/output parameters Data models. If you wish to read about the general Data models used in the ICT Platform or the System Architecture in general, please go here.

OpenAPI Specifications

All OpenAPI specification files can be found here. In detail:

  • Common definitions used by all services.

  • Eco-credits Calculator providing the Eco-credits calculation library functions as a REST service.

  • End User Module service for consumer applications. Eco-account access is done via this service.

  • Recycle Module service for the smart bin recycling use case.

  • Retailer Module service for the retailer applications. Product properties/Eco-points access and anonymous Eco-account access for purchase history updates on new purchases.

How to use the OpenAPI specifications

Recources

Source Code Generation

In order to generate source code for the programming language of your choice, you need to install the OpenAPI Generator or integrate him in your build system. From there you can use the OpenAPI specification that you need from the list above and generate the source code that will be the base of your project. On top of the generated code you implement the business logic of the application.

Examples

You can find Java examples here.

Java Prerequisites

The examples use Maven for the build system and integrate the OpenAPI source code generation into the build of the example code.

Install Java 8 SDK and Maven on your environment. All commands in the example instructions are for the Bash shell, you can easily modify them for the needs of your system’s shell. They should work as is in every Linux, BSD OS using the Bash shell and also in Windows using the Git Bash shell (you can find it here).

Web Application Description Language (WADL)

If OpenAPI and its generator does not fit the client developer’s tool chain, there is an alternative: all REST services provided by the ICCS ICT Platform provide a WADL document that describes the service paths, methods and data structures. The WADL URL is automatically generated by the service and is located in the relative path application.wadl. Here is the list of WADL document for each REST service:

Web Service Versions

All REST services and applications are deployed with a method that allows their version to be retrieved or shown to the client. In case or Web Applications with a human User Interface, check the footer of the page for the displayed version. For the REST services, there is a dedicated end-point that returns the version of the service:

https://circ4life.iccs.gr/_ModuleName_/resources/info/version

Each time a new version of the service is deployed, the previous one is kept for reference by changing the deployment context path URL to denote the version. The version of older deployments is added after the _ModuleName_ part of the path:

https://circ4life.iccs.gr/_ModuleName_/resources

becomes

https://circ4life.iccs.gr/_ModuleName_/_Version_/resources

For example once the version 0.0.3-dev is deployed as the latest, the 0.0.2-dev endpoint is changed to:

https://circ4life.iccs.gr/_ModuleName_/0.0.2-dev/resources

This will allow to keep a history of changes available to all clients and also help avoiding regressions.