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

Function  Endpoint Method Anonymous  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
Check if instance hosts one organization only /auth/singleorg GET X

Bookings

Function  Endpoint Method Anonymous  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 own booking /booking/ POST X
Create new booking for others /booking/ POST X
Get user's own upcoming bookings /booking/ GET X
Get filtered org bookings /booking/filter/ POST X

Locations

Function  Endpoint Method Anonymous  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

Function  Endpoint Method Anonymous  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

Function  Endpoint Method Anonymous  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
Function  Endpoint Method Anonymous  User  Org Admin  Super Admin
Get search results for keyword /search/{keyword} GET X

Settings

Function  Endpoint Method Anonymous  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

Function  Endpoint Method Anonymous  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

Function  Endpoint Method Anonymous  User  Org Admin  Super Admin
Get organization's stats /stats/ GET X

Users

Function  Endpoint Method Anonymous  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

Function  Endpoint Method Anonymous  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