# see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md
openapi: 3.1.0
info:
  title: eventer web API
  description: |-
    This is the official documentation of the (public) eventer web API,
    with which you can search and receive information about events in Germany.
    <br /><br />
    <b>Note: Because this project is in beta stage the offered events are restricted to the Chemnitz area in Saxony / Germany.</b>
    <br /><br />

    ## Making a request
    All URLs starts with `https://api.eventer.app/v1/`. The path is prefixed with the API version.
    If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the old URLs.
    Here's a simple example to search for upcoming "Party" events:
    [https://api.eventer.app/v1/events?search=Party](https://api.eventer.app/v1/events?search=Party)

    ## Date formats
    All timestamps (for requests and responses) are encoded in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
    with the following format: `YYYY-MM-DD'T'HH:mm'Z'`. The timezone used in responses is `UTC`.

    ## Pagination and Limits
    Most collection APIs paginate their results. Normally you can specify a limit with the parameter `limit`
    which must be greater than 0 and lower than 101 (default: 10). If there are more results to paginate for,
    you will get a `cursor` in the response which can be used as parameter for the next request (e.g. `&cursor=foo`),
    and so on until you get a response without cursor.

    ## Authentication
    This is an open API, no authentication needed.

    ## Help us make it better
    Please tell us how we can make the API better. If you have a specific feature request or if you found a bug,
    please feel free to contact us or contribute directly to our [git repository](https://github.com/eventer-org/eventer-openapi).
  version: '1.0'
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
- url: 'https://api.eventer.app/v1'
  variables: {}

tags:
  - name: events
    description: Retrieve events from all known and trusted sources of the eventer platform.
  - name: places
    description: Get details about the venues where the events take place.
  - name: pods
    description: Retrieve semantic data (JSON-LD) from specific sources (semantic pods).

paths:

  /events:
    get:
      tags:
        - events
      summary: /events
      description: |- 
        Use this endpoint to search for events over all known and trusted sources.
      parameters:
        - $ref: './events/components.yaml#/parameters/search'
        - $ref: './events/components.yaml#/parameters/starts_at_min'
        - $ref: './events/components.yaml#/parameters/starts_at_max'
        - $ref: './events/components.yaml#/parameters/categories'
        - $ref: './events/components.yaml#/parameters/google_place_ids'
        - $ref: './events/components.yaml#/parameters/geo_area'
        - $ref: './events/components.yaml#/parameters/geo_raster_points'
        - $ref: './events/components.yaml#/parameters/contexts'
        - $ref: './events/components.yaml#/parameters/updated_since'
        - $ref: './events/components.yaml#/parameters/include_deleted'
        - $ref: './events/components.yaml#/parameters/include_places'
        - $ref: './common/components.yaml#/parameters/limit'
        - $ref: './common/components.yaml#/parameters/cursor'
      responses:
        '200':
          $ref: './events/components.yaml#/responses/events'

  /events/{id}:
    get:
      tags:
        - events
      summary: /events/{id}
      description: Retrieve an event by id.
      parameters:
        - name: id
          in: path
          description: The id of the event to get.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The event.
          content:
            application/json:
              schema:
                $ref: './events/schemas.yaml#/Event'
        '404':
          description: Event not found.

  /places:
    get:
      tags:
        - places
      summary: /places
      description: Use this endpoint to search for places.
      parameters:
        - $ref: './places/components.yaml#/parameters/google_place_ids'
      responses:
        '200':
          description: The found places.
          content:
            application/json:
              schema:
                $ref: './places/components.yaml#/responses/places'

  /places/{id}:
    get:
      tags:
        - places
      summary: /places/{id}
      description: Retrieve a place by its google place id.
      parameters:
        - name: id
          in: path
          description: The google place id of the place to get.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The place.
          content:
            application/json:
              schema:
                $ref: './places/schemas.yaml#/Place'
        '404':
          description: Place not found.

  /pods/{pod}/events:
    get:
      tags:
        - pods
      summary: /pods/{pod}/events
      description: Retrieve semantic events from a specific account (pod).
      parameters:
        - name: pod
          in: path
          description: The name of the account (pod) to get events from.
          required: true
          schema:
            type: string
        - $ref: './pods/events/components.yaml#/parameters/startDateMin'
        - $ref: './pods/events/components.yaml#/parameters/startDateMax'
        - $ref: './pods/events/components.yaml#/parameters/dateModifiedMin'
        - $ref: './pods/events/components.yaml#/parameters/dateModifiedMax'
        - $ref: './pods/events/components.yaml#/parameters/sort'
        - $ref: './pods/events/components.yaml#/parameters/expand'
        - $ref: './common/components.yaml#/parameters/limit'
        - $ref: './common/components.yaml#/parameters/cursor'
      responses:
        '200':
          description: |-
            A list of events of this account (pod).
            The response is in JSON-LD format, using [Hydra](https://www.hydra-cg.com/) as response 
            structure to return a list of semantic events ([https://schema.org/Event](https://schema.org/Event)) with optional expansions.
            All properties starting with `@` are reserved for the [JSON-LD context](https://en.wikipedia.org/wiki/JSON-LD).
          content:
            application/application/ld+json:
              schema:
                $ref: './pods/events/components.yaml#/responses/events'
            application/json:
              schema:
                $ref: './pods/events/components.yaml#/responses/events'