# OneGov Org API

The headless Org API offers the following views:

- [Events](#events-view)
- [News](#news-view)
- [Topics](#topics-view)

We implement the called Collection+JSON standard established by Mike
Amundsen. For details please refer to [media types - collection & json](http://amundsen.com/media-types/collection/format/)

## Events View

The events view provides information about all the upcomig events.

`curl https://[base_url]/events`

Response:
A collection+JSON of items including paging

```
{
    "collection": {
        "version":"1.0",
        "href":"http://[base_url]/api/events",
        "links":[
            {
                "rel":"prev",
                "href":null
            },
            {
                "rel":"next",
                "href":"http://[base_url]/api/events?page=1"
            }
        ],
        "items": [
            {
                "href":"http://[base_url]/api/events/7482ec705b75434b8d54b3fe1b08a31e",
                "data" : [
                    {
                        "name":"title",
                        "value":"Beispielveranstaltung"
                    },
                    {
                        "name":"description",
                        "value":"Beschreibung der Veranstaltung"
                    },
                    {
                        "name":"organizer",
                        "value":"Ursula Winter"
                    },
                    {
                        "name":"organizer_email",
                        "value":"ursula.winter@beispiel.com"
                    },
                    {
                        "name":"organizer_phone",
                        "value":""
                    },
                    {
                        "name":"external_event_url",
                        "value":""
                    },
                    {
                        "name":"event_registration_url",
                        "value":""
                    },
                    {
                        "name":"price",
                        "value":""
                    },
                    {
                        "name":"tags",
                        "value":[]
                    },
                    {
                        "name":"start",
                        "value":"2025-01-23T11:00:00+00:00"
                    },
                    {
                        "name":"end",
                        "value":"2025-01-23T12:00:00+00:00"
                    },
                    {
                        "name":"location",
                        "value":"Govikon Gemeindehaus"
                    },
                    {
                        "name":"coordinates",
                        "value":
                            {
                                "lon":null,
                                "lat":null,
                                "zoom":null
                            }
                    },
                    {
                        "name":"created",
                        "value":"2025-01-08T10:08:46.716415+00:00"
                    },
                    {
                        "name":"modified",
                        "value":"2025-01-08T10:08:46.716415+00:00"
                    }
                ],
                "links" : [
                    {
                        "rel":"image",
                        "href":null
                    },
                    {
                        "rel":"pfd",
                        "href":null
                    }
                ]
            },
        ...
        ]
    }
}

```

## News View

The news view provides information about all the news.

`curl https://[base_url]/news`

## Topics View

The topics view provides information about all the topics, including
their hierarchical relationship via a `parent` link. Links to children
are implicit through their `parent` link.

`curl https://[base_url]/topics`


## Authorization

The API employs token-based authentication, which allows for unrestricted usage of the API without encountering rate-limiting restrictions.
A token will be valid for one hour, afterward you have to request a new one.

To authenticate via a token, you need an access key generated by the user.

1. In the settings generate an API access key.

Open The Settings:
![Settings](../_static/settings.png)

![Api Settings](../_static/settings_api.png)

![Api Keys](../_static/api_keys.png)

Here you can add a key, by supplying a name and clicking the blue submit button.
The key will be generated and displayed (see red box in image above).

Once you have a key, you can request a token. The token is used for all other requests.

2. To request a token, make a GET to `/api/authenticate` and provide the API access key via Bearer token or HTTP basic authentication in the username part (the password part is not used).
3. The token must be provided with all requests using a Bearer token or the username part of the HTTP basic authentication (the password part is not used).

### cURL example (Bearer token):

```bash
#/bin/bash

# Get the token
JSON=$(curl -H 'Authorization: Bearer <your api access key from UI>' \
    <your api url>/api/authenticate)

TOKEN=$(echo $JSON | sed "s/{.*\"token\":\"\([^\"]*\).*}/\1/g")

# Make a request with the token to any endpoint
curl -X GET \
   -H "Authorization: Bearer $TOKEN" \
   <your api url>/api/agencies
```

### cURL example (HTTP basic authentication):

```bash
#/bin/bash

# Get the token
JSON=$(curl -u <your api access key from UI>: \
    --silent <your api url>/api/authenticate)

TOKEN=$(echo $JSON | sed "s/{.*\"token\":\"\([^\"]*\).*}/\1/g")

# Make a request with the token to any endpoint
curl -X GET \
   -u $(echo -n "$TOKEN:") \
   --silent <your api url>/api/agencies
```