This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 857201. The European Commission assumes no responsibility for any content of this repository.

State API

Service which exposes an API to persist and query system state information.

What is this?

The State API service is part of the platform for media caching on trains. It exposes a REST API via which clients can update and query the platform's state. Also it provides a Gateway via which it multicasts state changes.

How does it work?

The figure below illustrates the software modules that make up the State API Service. The Cache State and Aggregator providers manage between the consumer interfaces -- the Event Gateway and HTTP API -- and the State DB. The State DB is a database that stores both the state of the cache as well as the current and historical configurations of the Aggregator (as defined by users through the Configurator UI).

Via the Event Gateway, consumers receive updates about changes in the status. An example of a consumer is the Sample Streaming Client. The gateway keeps the Sample Streamign Client informed about the current availability of cached streams. The Event Gateway primarily uses WebSockets for message transmission, but provides a number of fallback protocols for clients that do not support WebSockets. The Event Gateway is primarily intended for communication with consumers that are not part of the Platform. Real-time communication between platform components runs via the Message Streamer.

Using the HTTP API, consumers query or change the system state.

API

The State API exposes following HTTP endoints to query and change the system state:

• state-api/aggregator/config
  • GET: list available configurations
    • Returns: DataBasePage<AggregatorConfiguration>
  • POST: apply a new aggregator configuration
    • Body: AggregatorConfiguration
• state-api/cache-state
  • POST: initialise a new cache state
    • Body: CacheStateConfigItem[]
• state-api/cache-state/streams
  • GET: list of streaming media items
    • Returns: DataBasePage<CacheAsset>
• state-api/cache-state/streams/availability
  • GET: return availability statistic
    • Returns: Availability
• state-api/cache-state/streams/missing
  • GET: list streaming media items missing in the cache
    • Returns: DataBasePage<CacheAsset>
• state-api/cache-state/streams/available
  • GET: list of streaming media items available in the cache
    • Returns: DataBasePage<CacheAsset>
  • POST: set availability of one or more streaming media items
    • Body: CacheAssetInfo
• state-api/cache-state/streams/:id
  • GET: retrieve streaming media item with given id
    • Parameter id: caching URL hash of the streaming media item
    • Returns: CacheAsset[]
• state-api/cache-state/streams/:id/available
  • PATCH: set availability of one cache asset
    • Parameter id: caching URL hash of the cache asset
    • Body: boolean
• state-api/cache-state/media-items
  • GET: lists available media items
    • Returns: DataBasePage<MediaItem>
• state-api/cache-state/media-items/:id
  • GET: returns media item with given id
    • Parameter: id: id of the media item
    • Returns: MediaItem[]
• state-api/cache-state/media-items/:id/availability
  • GET: returns availability of streaming media items for the given media item id
    • Parameter: id: id of the media item
    • Returns: Availability
• state-api/cache-state/media-items/:id/available
  • GET: returns available cache assets for the given media item id
    • Parameter: id: id of the media item
    • Returns: DataBasePage<CacheAsset>
• state-api/cache-state/media-items/:id/missing
  • GET: returns missing cache assets for the given media item id
    • Parameter: id: id of the media item
    • Returns: DataBasePage<CacheAsset>
• state-api/cache-state/media-items/:id/streams
  • GET: returns cache assets for the given media item id
    • Parameter: id: id of the media item
    • Returns: DataBasePage<CacheAsset>

Technologie used

• Nest.js

Install, build, run

Note: Typically you would use the up.sh script from the Platform project to install, build and run this service as part of a composite of docker services. Read on if you intend to run the service directly on your host system.

Prerequestits: Following software needs to be installed on your host machine in order to execute the subsequent steps.

• Node.js
• NPM

First, git clone this project and change into its root directory. Than run the following command to install its dependencies:

$ npm install

You can than run the service in three different modes.

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

With following command you can build a docker image for this service. But again, typically you use the startup script up.sh of the Platform project to do the job.

$ docker build -t 5gv-state-api .