API v2

This describes the resources that make up the first public OpenMensa API v2. On problems contact us.

Schema

All API access happens over HTTPS. The only exception to this rule applies to unauthenticated readonly-requests - these are allowed via HTTP.

Endpoint: http://openmensa.org/api/v2

All pathes referenced throughout this document are meant to be relative to the API endpoint above.

Formats

Currently only JSON is supported.

All data is sent and received as JSON by default. Additionally the format for sending and recieving data can explicitly be stated during request via HTTP Accept-headers or URL suffix. The list of available formats includes JSON (resource.json), XML (resource.xml) and MessagePack (resource.msgpack) for mobile client speedup.

Encoding

Encoding for all requests and responses should be UTF-8.

Date and Time

All timestamps are returned in ISO 8601 format (UTC).

YYYY-MM-DDTHH:MM:SSZ

Dates will be returned without time information.

YYYY-MM-DD

Addresses

Postal address formats vary by country but at least the following information should be included in given order.

street address, postal code + city/town, country

Coordinates

Geographic coordinates are returned as an array of latitude and longitude.

[
  52.3877669669544,
  13.1209909915924
]

Examples

All examples are given in JSON notion (request as well as response bodies), for general rules how the XML will look see here.

Unless otherwise stated a response will contain all shown fields.

Authentication

Authentication happens via OAuth 2 - an access token included in every request to our API allows the client application to interact on behalf of the user with the OpenMensa server (only via SSL connections).

For details on howto use OAuth 2 with your OpenMensa client see here.

Pagination

Requests returning multiple items will be paginated to 10 items by default. You can specify the number of items per page using the limit parameter. Allowed values are between 1 and 100. The upper limit may be different for specific resources.

Further pages can be requested by specifying the page parameter. First page (the one you usually retrieve without explicitly specifying the page number) is page number 1.

Rate Limiting

None.

Client Errors

See here.