Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
595 lines (590 sloc) 13.8 KB
openapi: 3.0.2
info:
title: OpenFairDB API
version: 0.1.0
contact:
name: slowtec GmbH
url: 'https://slowtec.de'
license:
name: AGPLv3
url: 'https://github.com/slowtec/openfairdb/blob/master/LICENSE'
servers:
- url: 'https://api.ofdb.io/v0/'
description: Public production server
- url: 'https://nightly.ofdb.io/v0/'
description: Public unstable development server
paths:
/search:
get:
summary: Search for entries
tags:
- Search
parameters:
- name: text
in: query
schema:
type: string
- $ref: '#/components/parameters/BoundingBox'
- name: categories
in: query
schema:
type: string
description: |
An optional filter.
We currently use the following two:
- Initiative (non-commercial): `2cd00bebec0c48ba9db761da48678134`
- Company: `77b3c33a92554bcf8e8c2c86cedd6f6f`
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResult'
'/entries':
post:
summary: Create an entry
tags:
- Entries
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
responses:
'200':
description: Successful response
'/entries/{id}':
get:
summary: Get an entry
tags:
- Entries
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
'/ratings/{id}':
get:
summary: Get a specific rating
tags:
- Ratings
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Rating'
/categories/:
get:
summary: Get available categories
tags:
- Categories
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Category'
'/categories/{id}':
get:
summary: Get a specific categories
tags:
- Categories
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Category'
/events:
get:
tags:
- Events
summary: Receive events
parameters:
- name: tag
in: query
description: Filter events by tags
schema:
type: array
items:
type: string
- $ref: '#/components/parameters/BoundingBox'
- name: created_by
in: query
description: The email address of the event creator (only available with valid API token)
schema:
type: string
- name: start_min
in: query
description: Filter events by `event.start` >= `start_min`
schema:
type: number
- name: start_max
in: query
description: Filter events by `event.start` <= `start_max`
schema:
type: number
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Event'
post:
tags:
- Events
summary: Create a new event
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'201':
description: Created a new event
content:
application/json:
schema:
description: The ID of the created event
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
'/events/{id}':
get:
summary: Get a single event
tags:
- Events
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
put:
summary: Update an event
tags:
- Events
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Sucessfully updated the event
'401':
$ref: '#/components/responses/UnauthorizedError'
delete:
summary: Delete an event
tags:
- Events
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Sucessfully deleted the event
'401':
$ref: '#/components/responses/UnauthorizedError'
'/login':
post:
summary: User login
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
password:
type: string
responses:
'200':
description: Sucessfull response
'/logout':
post:
summary: User logout
tags:
- Users
responses:
'200':
description: Sucessfull response
'/users/{username}':
get:
summary: Get user data
tags:
- Users
parameters:
- name: username
in: path
required: true
schema:
type: string
responses:
'200':
description: Sucessfull response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/tags:
get:
summary: Get tags
tags:
- Tags
responses:
'200':
description: Sucessfull response
content:
application/json:
schema:
type: array
items:
type: string
/count/entries:
get:
summary: Get number of entries
tags:
- Stats
responses:
'200':
description: Sucessfull response
content:
application/json:
schema:
type: integer
/count/tags:
get:
summary: Get number of tags
tags:
- Stats
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: integer
/server/version:
get:
summary: Get current server version
tags:
- Stats
responses:
'200':
description: Successful response
content:
text/plain:
schema:
type: string
/server/api.yaml:
get:
summary: Get current API documentation
tags:
- Stats
responses:
'200':
description: Successful response
content:
text/yaml:
schema:
type: string
/export/entries.csv:
get:
summary: Export data as CSV
description: |
**Example**:
Export all entries in Germany:
`/export/entries.csv?bbox=47.49,0.79,54.63,18.30`
If you want to find out the coordinates for other map areas,
open "network" in the "developer tools" in your browser
and look at the search request under at the value of `bbox`.
tags:
- Export
parameters:
- $ref: '#/components/parameters/BoundingBox'
responses:
'200':
description: Successful response
content:
text/csv:
schema:
type: string
components:
schemas:
Entry:
properties:
id:
type: string
readOnly: true
version:
type: integer
created:
type: integer
title:
type: string
description:
type: string
lat:
type: number
lng:
type: number
street:
type: string
zip:
type: string
city:
type: string
country:
type: string
email:
type: string
telephone:
type: string
homepage:
type: string
categories:
type: array
items:
type: string
tags:
type: array
items:
type: string
ratings:
type: array
items:
type: string
image_url:
type: string
image_link_url:
type: string
license:
type: string
Category:
properties:
id:
type: string
readOnly: true
created:
type: integer
version:
type: integer
name:
type: string
Rating:
properties:
id:
type: string
readOnly: true
title:
type: string
created:
type: integer
value:
type: integer
context:
type: string
source:
type: string
comments:
type: array
items:
$ref: '#/components/schemas/RatingComment'
RatingComment:
properties:
id:
type: string
readOnly: true
created:
$ref: '#/components/schemas/UnixTime'
text:
type: string
User:
properties:
username:
type: string
email:
type: string
BboxSubscription:
properties:
id:
type: string
readOnly: true
south_west_lat:
type: number
south_west_lng:
type: number
north_east_lat:
type: number
north_east_lng:
type: number
SearchResult:
properties:
visible:
description: The entries that are in the given bounding box (bbox, area of the map).
type: array
items:
type: object
properties:
id:
type: string
lat:
type: number
lng:
type: number
invisible:
description: Up to 5 entries outside the bbox.
type: array
items:
type: object
properties:
id:
type: string
lat:
type: number
lng:
type: number
Event:
properties:
id:
type: string
readOnly: true
title:
type: string
description:
type: string
start:
$ref: '#/components/schemas/UnixTime'
end:
$ref: '#/components/schemas/UnixTime'
created_at:
$ref: '#/components/schemas/UnixTime'
created_by:
type: string
description: |
The email address of the user who is responsible for the content.
This information is only available for authorized organizations.
lat:
type: number
format: float
lng:
type: number
format: float
street:
type: string
zip:
type: string
city:
type: string
country:
type: string
email:
type: string
description: The public email address
example: info@example.com
telephone:
type: string
tags:
type: array
items:
type: string
example: [organic, csa]
homepage:
type: string
registration:
type: string
enum:
- email
- telephone
- homepage
example: telephone
description: Type of registration
organizer:
type: string
example:
title: A great event
start: 1547403505
created_by: testuser@example.com
telephone: "0123456789"
tags: [awesome, organic]
registration: "telephone"
UnixTime:
type: integer
format: int64
description: 'Unix Time (number of seconds since 00:00::00 1. January, 1970, UTC)'
example: 1547403509
parameters:
BoundingBox:
name: bbox
in: query
description: Bounding Box
schema:
type: string
example: "42.27,-7.97,52.58,38.25"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
responses:
UnauthorizedError:
description: Access token is missing or invalid