Respa API tutorial

Resource reservation system

The Respa API is a resource reservation system provided by the cities of Helsinki and Espoo. It enables API clients to

[Here is a picture of the data model of the API]

a picture

Basic usage of the API.

The most common use cases of the API are described here.

Listing all units.

To find out which service points (like branch libraries) offer resources that are reservable, make a request to get all the units.

Request:

GET /v1/unit/ 

Response:

{
"previous": null,
"count": 2,
"results": [
    {
        "modified_by": null,
        "address_zip": null,
        "id": "unit_1",
        "picture_caption": null,
        "description": null,
        "location": null,
        "time_zone": "Europe/Helsinki",
        "slug": "unit-1",
        "email": null,
        "created_at": "2016-03-22T13:30:02.291013Z",
        "opening_hours_today": {
            "2016-03-22": [
                {
                    "closes": null,
                    "opens": null
                }
            ]
        },
        "created_by": null,
        "picture_url": null,
        "name": {
            "fi": "Unit 1"
        },
        "street_address": null,
        "www_url": null,
        "phone": null,
        "address_postal_full": null,
        "modified_at": "2016-03-22T13:30:02.291043Z"
    },
    {
        "modified_by": null,
        "address_zip": null,
        "id": "unit_2",
        "picture_caption": null,
        "description": null,
        "location": null,
        "time_zone": "Europe/Helsinki",
        "slug": "unit-2",
        "email": null,
        "created_at": "2016-03-22T13:30:02.293852Z",
        "opening_hours_today": {
            "2016-03-22": [
                {
                    "closes": null,
                    "opens": null
                }
            ]
        },
        "created_by": null,
        "picture_url": null,
        "name": {
            "fi": "Unit 2"
        },
        "street_address": null,
        "www_url": null,
        "phone": null,
        "address_postal_full": null,
        "modified_at": "2016-03-22T13:30:02.293877Z"
    }
],
"next": null }

The field opening_hours_today specifies in a structured way when the unit is open for customers. All the resources within the unit are restricted to the specified opening hours.

Listing all resources.

A resource is anything available for the customers to reserve for their use – mostly reservable rooms or equipment. Similarly, if you wish to get a listing of all the resources available for reservations, make a GET request to the root of the resource endpoint:

GET /v1/resource/

Response:

{
"previous": null,
"count": 4,
"results": [
    {
        "min_period": "00:30:00",
        "public": true,
        "id": "r1a",
        "reservable": true,
        "location": null,
        "available_hours": null,
        "type": {
            "id": "type_1",
            "main_type": "space",
            "name": {
                "fi": "Type 1"
            }
        },
        "reservations": null,
        "area": null,
        "purposes": [],
        "name": {
            "fi": "Resource 1a"
        },
        "user_permissions": {
            "is_admin": false,
            "can_make_reservations": true
        },
        "reservation_info": null,
        "slug": "resource-1a",
        "description": null,
        "modified_at": "2016-03-22T13:30:02.297079Z",
        "images": [],
        "unit": "unit_1",
        "modified_by": null,
        "people_capacity": null,
        "need_manual_confirmation": false,
        "authentication": "",
        "created_at": "2016-03-22T13:30:02.297056Z",
        "created_by": null,
        "opening_hours": [
            {
                "date": "2016-03-22",
                "closes": null,
                "opens": null
            }
        ],
        "max_reservations_per_user": null,
        "equipment": [],
        "max_period": null
    },
    {
        "min_period": "00:30:00",
        "public": true,
        "id": "r1b",
        "reservable": true,
        "location": null,
        "available_hours": null,
        "type": {
            "id": "type_1",
            "main_type": "space",
            "name": {
                "fi": "Type 1"
            }
        },
        "reservations": null,
        "area": null,
        "purposes": [],
        "name": {
            "fi": "Resource 1b"
        },
        "user_permissions": {
            "is_admin": false,
            "can_make_reservations": true
        },
        "reservation_info": null,
        "slug": "resource-1b",
        "description": null,
        "modified_at": "2016-03-22T13:30:02.299503Z",
        "images": [],
        "unit": "unit_1",
        "modified_by": null,
        "people_capacity": null,
        "need_manual_confirmation": false,
        "authentication": "",
        "created_at": "2016-03-22T13:30:02.299466Z",
        "created_by": null,
        "opening_hours": [
            {
                "date": "2016-03-22",
                "closes": null,
                "opens": null
            }
        ],
        "max_reservations_per_user": null,
        "equipment": [],
        "max_period": null
    },
    {
        "min_period": "00:30:00",
        "public": true,
        "id": "r2a",
        "reservable": true,
        "location": null,
        "available_hours": null,
        "type": {
            "id": "type_1",
            "main_type": "space",
            "name": {
                "fi": "Type 1"
            }
        },
        "reservations": null,
        "area": null,
        "purposes": [],
        "name": {
            "fi": "Resource 2a"
        },
        "user_permissions": {
            "is_admin": false,
            "can_make_reservations": true
        },
        "reservation_info": null,
        "slug": "resource-2a",
        "description": null,
        "modified_at": "2016-03-22T13:30:02.302406Z",
        "images": [],
        "unit": "unit_2",
        "modified_by": null,
        "people_capacity": null,
        "need_manual_confirmation": false,
        "authentication": "",
        "created_at": "2016-03-22T13:30:02.302380Z",
        "created_by": null,
        "opening_hours": [
            {
                "date": "2016-03-22",
                "closes": null,
                "opens": null
            }
        ],
        "max_reservations_per_user": null,
        "equipment": [],
        "max_period": null
    },
    {
        "min_period": "00:30:00",
        "public": true,
        "id": "r2b",
        "reservable": true,
        "location": null,
        "available_hours": null,
        "type": {
            "id": "type_1",
            "main_type": "space",
            "name": {
                "fi": "Type 1"
            }
        },
        "reservations": null,
        "area": null,
        "purposes": [],
        "name": {
            "fi": "Resource 2b"
        },
        "user_permissions": {
            "is_admin": false,
            "can_make_reservations": true
        },
        "reservation_info": null,
        "slug": "resource-2b",
        "description": null,
        "modified_at": "2016-03-22T13:30:02.304747Z",
        "images": [],
        "unit": "unit_2",
        "modified_by": null,
        "people_capacity": null,
        "need_manual_confirmation": false,
        "authentication": "",
        "created_at": "2016-03-22T13:30:02.304723Z",
        "created_by": null,
        "opening_hours": [
            {
                "date": "2016-03-22",
                "closes": null,
                "opens": null
            }
        ],
        "max_reservations_per_user": null,
        "equipment": [],
        "max_period": null
    }
],
"next": null }

The field need_manual_confirmation is important, because it specifies whether you can automatically book the resource immediately, or whether there is an additional confirmation required from the resource owner.

Listing resources available at a specified time interval

Perhaps more interestingly, you can also restrict the results to resources which are available at a specified time interval.

Request:

GET /v1/resource/r1a/?start=2016-03-22T00:00:00%2b02:00&end=2016-03-23T00:00:00%2b02:00&during_closing=true

Response:

{
"min_period": "00:30:00",
"public": true,
"id": "r1a",
"reservable": true,
"location": null,
"available_hours": [
    {
        "starts": "2016-03-22T00:00:00+02:00",
        "ends": "2016-03-23T00:00:00+02:00"
    }
],
"type": {
    "id": "type_1",
    "main_type": "space",
    "name": {
        "fi": "Type 1"
    }
},
"reservations": [],
"area": null,
"purposes": [],
"name": {
    "fi": "Resource 1a"
},
"user_permissions": {
    "is_admin": false,
    "can_make_reservations": true
},
"reservation_info": null,
"slug": "resource-1a",
"description": null,
"modified_at": "2016-03-22T13:30:02.297079Z",
"images": [],
"unit": {
    "modified_by": null,
    "address_zip": null,
    "id": "unit_1",
    "picture_caption": null,
    "description": null,
    "location": null,
    "time_zone": "Europe/Helsinki",
    "slug": "unit-1",
    "email": null,
    "created_at": "2016-03-22T13:30:02.291013Z",
    "opening_hours_today": {
        "2016-03-22": [
            {
                "closes": null,
                "opens": null
            }
        ]
    },
    "created_by": null,
    "picture_url": null,
    "name": {
        "fi": "Unit 1"
    },
    "street_address": null,
    "www_url": null,
    "phone": null,
    "address_postal_full": null,
    "modified_at": "2016-03-22T13:30:02.291043Z"
},
"modified_by": null,
"people_capacity": null,
"need_manual_confirmation": false,
"authentication": "",
"created_at": "2016-03-22T13:30:02.297056Z",
"created_by": null,
"opening_hours": [
    {
        "date": "2016-03-22",
        "closes": "2016-03-22T22:00:00+02:00",
        "opens": "2016-03-22T08:00:00+02:00"
    },
    {
        "date": "2016-03-23",
        "closes": null,
        "opens": null
    }
],
"max_reservations_per_user": null,
"equipment": [],
"max_period": null }