openapi.yaml

openapi: 3.0.2
info:
  title: OpenFairDB API
  version: 0.5.7
  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 ordered by their total rating
      tags:
        - Search
      parameters:
        - $ref: '#/components/parameters/BoundingBox'
        - name: categories
          in: query
          schema:
            type: string
          description: |
            Comma-separated list if category identifiers.
            We currently use the following two:
            - Initiative (non-commercial): `2cd00bebec0c48ba9db761da48678134`
            - Company (commercial): `77b3c33a92554bcf8e8c2c86cedd6f6f`
        - name: ids
          description: Comma-separated list of entry identifiers
          in: query
          schema:
            type: string
        - name: tags
          description: Comma-separated list of tags
          in: query
          schema:
            type: string
        - name: text
          in: query
          schema:
            type: string
        - name: limit
          description: Maximum number of entries that should be returned. The upper bound for all requests is 250!
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  '/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/{ids}':
    get:
      summary: Get multiple entries
      tags:
        - Entries
      parameters:
        - name: ids
          description: Comma-separated list of entry identifiers
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entry'

  '/ratings/{ids}':
    get:
      summary: Get multiple ratings
      tags:
        - Ratings
      parameters:
        - name: ids
          description: Comma-separated list of rating identifiers
          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/{ids}':
    get:
      summary: Get multiple categories
      tags:
        - Categories
      parameters:
        - name: ids
          description: Comma-separated list of category identifiers
          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'
  '/users/reset-password-request':
    post:
      summary: Request a password reset
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_or_username:
                  type: string
      responses:
        '200':
           description: Sucessfull response
  '/users/reset-password':
    post:
      summary: Request a users password
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_or_username:
                  type: string
                token:
                  type: string
                new_password:
                  type: string
      responses:
        '200':
           description: Sucessfull response
  /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
    SearchResponse:
      properties:
        visible:
          description: The entries that are in the given bounding box (bbox, area of the map).
          type: array
          items:
            $ref: '#/components/schemas/SearchEntry'
        invisible:
          description: Up to 5 entries outside the bbox.
          type: array
          items:
            $ref: '#/components/schemas/SearchEntry'
    SearchEntry:
      description: The compact view of an entry as returned in search results.
      properties:
        id:
          type: string
        lat:
          type: number
        lng:
          type: number
        title:
          type: string
        description:
          type: string
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        ratings:
          $ref: '#/components/schemas/AvgRatings'
    AvgRatings:
      description: All average ratings of an entry.
      properties:
        total:
          type: number
        diversity:
          type: number
        fairness:
          type: number
        humanity:
          type: number
        renewable:
          type: number
        solidarity:
          type: number
        transparency:
          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