OrganiCity Scenarios

Version: 1.0

This API specifies the API of the OrganiCity Scenario Tool.

It comprises functionality for the following parts:

Schemes: https

Base URL: https://scenarios.organicity.eu/api/v1

Summary

Path Operation Description
/scenarios GET

Request a filtered, sorted list of scenarios

Paths

Request a filtered, sorted list of scenarios

GET /scenarios

Tags: Scenarios

This endpoint is the default access to request a list of current scenarios according to various filters. It will always return the most current versions of a scenario; older versions can be requested through the appropriate other endpoints. This endpoint allows a couple of different filtering and sorting methods.

uuid

This allows to get the scenario with a specific UUID.

query string
q

This allows a sort of full text search.

query string
creator

This allows to filter by the creatior UUID.

query string
sectors

This allows to filter by the sectors. Multiple sectors can be selected with a comma.

query string
actors

This allows to filter by the actors. Multiple sectors can be selected with a comma.

query string
devices

This allows to filter by the devices. Multiple sectors can be selected with a comma.

query string
sortBy

The field that the selected list of scenarios should be sorted by. The sorting is applied before skip and limit are evaulated.

query string (fieldname) , x ∈ { title , summary , narrative , creator , timestamp (default) , thumbnail , actors , sectors , devices , dataSources }
sortDir

Specifies if the sorted field selected by sortBy is sorted in ascending (asc) or descending (desc) order.

query string , x ∈ { asc (default) , desc }
skip

In collaboration with limit, this parameter facilitates paging the returned scenarios. The value supplied for skip denotes the number of scenarios to skip after sorting.

query integer , { x ∈ ℤ | x ≥ 0 }
limit

Denotes the maximum number of scenarios to return. After the list of scenarios is filtered and sorted and skip scenarios have been discarded, this returns the first n remaining scenarios.

query integer , { x ∈ ℤ | 1 ≤ x ≤ 100 }

application/json

200 OK

The list of scenarios was successfully determined and extracted, and is returned in the body.

Scenarios: object[]

The list of scenarios filtered, sorted and paginated according to the requests' parameters.

Reference: Scenario

Schema definitions

DataSource: object

A data source object is an descriptor of a source of data.

uuid: string (uuid)

A unique uuid identifying this data source.

href: string (url)

A link to or url identifying the original data source.

description: string

A textual description of this data source, which may contain markdown formatting.

Scenario: object

A scenario is a user story that describes a way, in which the OrganiCity data can be used to improve the user's city.

uuid: string (uuid)

A unique uuid identifying this scenario.

version: integer , { x ∈ ℤ | x ≥ 1 }

This scenarios' version, used for identifying changes. This field is incremented by the server.

title: string

The title of this scenario as plain text.

summary: string

The summary of this scenario as plain text.

narrative: string

The narrative of this scenario, which may contain markdown formatting.

creator: string (uuid)

The uuid of the user that initially created this scenario.

timestamp: string (date-time)

The creation time of this scenario. If no time is given, this defaults to the current time.

thumbnail: string

The name of the file containing the thumbnail of this scenario.

actors: string[]

The list of actors that are involved with this scenario.

string
sectors: string[]

The list of sectors that this scenario belongs to.

string
devices: string[]

The list of devices that this scenario employs.

string
dataSources: string[]

The list of data sources that this scenario employs.

string

User: object

A registered user.

uuid: string (uuid)

The UUID of this user.

name: string

The user's name, by which she is refered to in the Gui.

roles: string[]

A list of roles that this user is assigned. These roles form the basis for access control, and should thusly be treated carefully.

string
gender: string (m or f)

The user's gender. This might be m or f.

local: object

Information about the local-login authentication scheme for this user.

email: string (email)

The email address that this user uses to log in via local login.