Skip to content

Rest API

Seatsurfing provides and uses a couple of REST APIs. The REST APIs are used by the mobile and web app as well as the administrator web interface.

Authorization checks

Each API function is protected by authorization checks:

  • First check: Role of the user (anonymous, user, org admin, super admin)
  • Second check: Organisation membership

Status Codes

Seatsurfing's REST API uses the well known HTTP status codes to inform the caller about the result and eventual errors:

  • 201 Created: Object created (includes HTTP response header X-Object-ID)
  • 204 No Content: Object updated or no response content
  • 400 Bad Request: Malformed request or incomplete JSON
  • 401 Unauthorized: JWT in HTTP request header Authorization missing, expired or invalid
  • 403 Forbidden: Authorized, by user has no access to requested resource
  • 404 Not found: Object not found
  • 409 Conflict: Conflicting request
  • 500 Internal Server Error

Roles

  • Anonymous: Every user allowed, no authorization required
  • User: Authorized user who is a member of an organisation
  • Org Admin: An organisation's administrator
  • Super Admin: Global administrator with access to all organisations and all functions

Endpoints

Authentication

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Password Login /auth/login POST X
Preflight Login to check for available login methods /auth/preflight POST X
Perform OAuth Login /auth/{id}/login/{type} GET X
OAuth Callback (server to server) /auth/{id}/callback GET X
Retrieve JWT from frontend / app after OAuth Login /auth/verify/{id} GET X

Bookings

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one own booking /booking/{id} GET X
Update one own booking /booking/{id} PUT X
Delete one own booking /booking/{id} DELETE X
Create new booking /booking/ POST X
Get user's own upcoming bookings /booking/ GET X
Get filtered org bookings /booking/filter/ POST X

Locations

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one location /location/{id} GET X
Update one location /location/{id} PUT X
Delete one location /location/{id} DELETE X
Get all organization's location /location/ GET X
Create a new location /location/ POST X
Get location map /location/{id}/map GET X
Set/update location map /location/{id}/map POST X

Spaces

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one space /location/{locationId}/space/{id} GET X
Update one space /location/{locationId}/space/{id} PUT X
Delete one space /location/{locationId}/space/{id} DELETE X
Get all spaces in a location /location/{locationId}/space/ GET X
Create a new space in a location /location/{locationId}/space/ POST X
Get spaces with availability information for a specific time period /location/{locationId}/space/availability POST X

Organisations

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one organization /organization/{id} GET X
Update one organization /organization/{id} PUT X
Delete one organization /organization/{id} DELETE X
Get all organizations /organization/ GET X
Create a new organization /organization/ POST X
Get organization for domain /organization/domain/{domain} GET X
Get all domains for an organization /organization/{id}/domain/ GET X
Add a new domain to an organization /organization/{id}/domain/{domain} POST X
Remove a domain from an organization /organization/{id}/domain/{domain} DELETE X
Verify DNS-TXT-Record for a domain /organization/{id}/domain/{domain}/verify POST X
Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get search results for keyword /search/{keyword} GET X

Settings

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get all settings /setting/ GET X
Update all settings /setting/ PUT X
Get one setting /setting/{name} GET X
Update one setting /setting/{name} PUT X

Signup

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Signup and init double-opt-in /signup/ POST X
Complete double-opt-in process /signup/confirm/{id} POST X

Statistics

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get organization's stats /stats/ GET X

Users

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one user /user/{id} GET X
Update one user /user/{id} PUT X
Delete one user /user/{id} DELETE X
Set a user's password /user/{id}/password PUT X
Get all users of an organization /user/ GET X
Create a new user in an organization /user/ POST X
Get user's own details /user/me GET X

Auth Providers

Funktion  Endpunkt Methode  Anonym  User  Org Admin  Super Admin
Get one auth provider /auth-provider/{id} GET X
Update one auth provider /auth-provider/{id} PUT X
Delete one auth provider /auth-provider/{id} DELETE X
Get all auth providers of an organization /auth-provider/ GET X
Create a new auth provider in an organization /auth-provider/ POST X
Get public auth provider information for an organization /auth-provider/org/{id} GET X