OneGov Org API

The headless Org API offers the following views:

• Events

• News

• Topics

We implement the called Collection+JSON standard established by Mike Amundsen. For details please refer to media types - collection & json

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:

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):

#/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):

#/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