API docs by Redocly

Vahana-API (1)

Download OpenAPI specification:

URL: https://github.com/sergej-stk/vahana Terms of Service

A ride-sharing API for connecting drivers and passengers.

User Endpoint

Endpoints for user data.

Get user by ID [USER, ADMIN]

Retrieves the details of a user by their unique identifier.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9"
}

Delete user by ID [ADMIN]

Deletes a user by their unique identifier.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Change user information's [ADMIN]

Change the details of an user by id.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
username
string [ 1 .. 100 ] characters

The user's username. Username must be unique.

email
string [ 1 .. 320 ] characters

The user's email address, used for communication and login.

lastname
string [ 1 .. 100 ] characters

The user's last name.

firstname
string [ 1 .. 100 ] characters

The user's first name.

phonenumber
string or null [ 10 .. 20 ] characters ^\+?[0-9]{1,3}?[ \-]?\(?[0-9]{2,4}\)?[ \-]?[0...

The user's phone number. Valid formats include:

  • +49 170 1234567
  • +1-800-123 4567
  • (+44) 20 7946 0958
  • +33 1 70 12 34 56
  • +49-40-123 4567
  • (+1) 123 456 7890
  • +41 (0) 44 567 8901

object (Update Address)

Represents the data required to update an address.

Responses

Request samples

Content type
application/json
{
  • "username": "JohnDoe123",
  • "email": "[email protected]",
  • "lastname": "Doe",
  • "firstname": "John",
  • "phonenumber": "+49 170 1234567",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "role": "USER",
  • "lastname": "Doe",
  • "firstname": "John",
  • "email": "[email protected]",
  • "phonenumber": "+49 170 1234567",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "address": {
    }
}

Get authenticated user [USER, ADMIN]

Retrieves the details of the currently authenticated user.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "role": "USER",
  • "lastname": "Doe",
  • "firstname": "John",
  • "email": "[email protected]",
  • "phonenumber": "+49 170 1234567",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "address": {
    }
}

Delete current user [USER, ADMIN]

Deletes the currently authenticated user.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Change authenticated user information's [USER, ADMIN]

Change the details of the currently authenticated user.

Authorizations:
bearerAuth
Request Body schema: application/json
required
username
string [ 1 .. 100 ] characters

The user's username. Username must be unique.

email
string [ 1 .. 320 ] characters

The user's email address, used for communication and login.

lastname
string [ 1 .. 100 ] characters

The user's last name.

firstname
string [ 1 .. 100 ] characters

The user's first name.

phonenumber
string or null [ 10 .. 20 ] characters ^\+?[0-9]{1,3}?[ \-]?\(?[0-9]{2,4}\)?[ \-]?[0...

The user's phone number. Valid formats include:

  • +49 170 1234567
  • +1-800-123 4567
  • (+44) 20 7946 0958
  • +33 1 70 12 34 56
  • +49-40-123 4567
  • (+1) 123 456 7890
  • +41 (0) 44 567 8901

object (Update Address)

Represents the data required to update an address.

Responses

Request samples

Content type
application/json
{
  • "username": "JohnDoe123",
  • "email": "[email protected]",
  • "lastname": "Doe",
  • "firstname": "John",
  • "phonenumber": "+49 170 1234567",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "role": "USER",
  • "lastname": "Doe",
  • "firstname": "John",
  • "email": "[email protected]",
  • "phonenumber": "+49 170 1234567",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "address": {
    }
}

Get all users [USER, ADMIN]

Retrieves a paginated list of all users.

Authorizations:
bearerAuth
query Parameters
page
string or null
Default: "0"
Example: page=0

Page number for pagination.

size
string or null <= 100
Default: "100"
Example: size=100

Number of rides per page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageable": {
    },
  • "last": true,
  • "totalPages": 0,
  • "totalElements": 0,
  • "first": true,
  • "size": 0,
  • "number": 0,
  • "sort": {
    },
  • "numberOfElements": 0,
  • "empty": true
}

Notification Endpoint

Endpoints for user notifications.

Mark a notification as read [USER, ADMIN]

Updates the read status of a notification by its ID.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "user_id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "type": "RIDE",
  • "message": "Ride 232342 was canceled.",
  • "read": true
}

Retrieve a specific notification by ID [USER, ADMIN]

Fetches a single notification by its unique identifier.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "user_id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "type": "RIDE",
  • "message": "Ride 232342 was canceled.",
  • "read": true
}

Get all notifications for the authenticated user [USER, ADMIN]

Retrieves a list of notifications filtered by the provided parameters.

Authorizations:
bearerAuth
query Parameters
page
string or null
Default: "0"
Example: page=0

Page number for pagination.

size
string or null <= 100
Default: "100"
Example: size=100

Number of rides per page.

read
string or null
Default: "false"
Example: read=true

Read status of notifications.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageable": {
    },
  • "last": true,
  • "totalPages": 0,
  • "totalElements": 0,
  • "first": true,
  • "size": 0,
  • "number": 0,
  • "sort": {
    },
  • "numberOfElements": 0,
  • "empty": true
}

Picture Endpoint

Endpoints for pictures.

Get picture by ID [USER, ADMIN]

Retrieve a picture by its unique identifier.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Update picture by ID [USER, ADMIN]

Update a picture by its unique identifier.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
picture
required
string <binary>

Responses

Request samples

Content type
application/json
{
  • "picture": "string"
}

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Rides Endpoint

Endpoints for rides.

Get all Rides [USER, ADMIN]

Retrieves a paginated list of all available rides.

Authorizations:
bearerAuth
query Parameters
page
string or null
Default: "0"
Example: page=0

Page number for pagination.

size
string or null <= 100
Default: "100"
Example: size=100

Number of rides per page.

sortby
string or null
Default: "departure"
Example: sortby=departure

Field by which results should be sorted (departure, created).

sortdirection
string or null
Default: "DESC"
Example: sortdirection=DESC

Sorting direction: ASC for ascending, DESC for descending (CASE SENSITIVE).

status
string or null
Example: status=ACTIVE

Filter by status: PLANNED, ACTIVE, CANCELED, COMPLETED; (Default: All values)

origincity
string or null
Example: origincity=Berlin

Search by origincity

destinationcity
string or null
Example: destinationcity=Wolfsburg

Search by destinationcity

username
string or null
Example: username=sergej-stk

Search by username of creator

userid
string or null
Example: userid=d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9

Search by id of creator

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageable": {
    },
  • "last": true,
  • "totalPages": 0,
  • "totalElements": 0,
  • "first": true,
  • "size": 0,
  • "number": 0,
  • "sort": {
    },
  • "numberOfElements": 0,
  • "empty": true
}

Create a Ride [USER, ADMIN]

Creates a new ride based on the provided ride details.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (Update Address)

Represents the data required to update an address.

object (Update Address)

Represents the data required to update an address.

departure
string <date-time>

The planned departure time of the ride in UTC format.

available_seats
integer <int32>

The number of available seats for the ride.

Responses

Request samples

Content type
application/json
{
  • "origin": {
    },
  • "destination": {
    },
  • "departure": "2025-03-02T14:30:00Z",
  • "available_seats": 4
}

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "departure": "2025-03-02T14:30:00Z",
  • "created": "2025-03-02T14:30:00Z",
  • "driver": {
    },
  • "origin": {
    },
  • "destination": {
    },
  • "status": "PLANNED",
  • "available_seats": 4
}

Join a ride [USER, ADMIN]

Allows an authenticated user to join a ride by providing the ride ID.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "created": "2025-03-02T14:30:00Z"
}

Get a ride by ID [USER, ADMIN]

Retrieves a single ride based on the provided ride ID.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "departure": "2025-03-02T14:30:00Z",
  • "created": "2025-03-02T14:30:00Z",
  • "driver": {
    },
  • "origin": {
    },
  • "destination": {
    },
  • "status": "PLANNED",
  • "available_seats": 4
}

Delete a ride by ID [ADMIN]

Deletes a ride based on the provided ride ID. Only admins can perform this action.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Get all Participants for a ride by ID [USER, ADMIN]

Retrieves a User list based on the provided ride ID.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
query Parameters
page
string or null
Default: "0"
Example: page=0

Page number for pagination.

size
string or null <= 100
Default: "100"
Example: size=100

Number of rides per page.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageable": {
    },
  • "last": true,
  • "totalPages": 0,
  • "totalElements": 0,
  • "first": true,
  • "size": 0,
  • "number": 0,
  • "sort": {
    },
  • "numberOfElements": 0,
  • "empty": true
}

Get rides created by authenticated user [USER, ADMIN]

Retrieves a paginated list of rides that belong to the currently authenticated user.

Authorizations:
bearerAuth
query Parameters
page
string or null
Default: "0"
Example: page=0

Page number for pagination.

size
string or null <= 100
Default: "100"
Example: size=100

Number of rides per page.

sortby
string or null
Default: "departure"
Example: sortby=departure

Field by which results should be sorted (departure, created).

sortdirection
string or null
Default: "DESC"
Example: sortdirection=DESC

Sorting direction: ASC for ascending, DESC for descending (CASE SENSITIVE).

status
string or null
Example: status=ACTIVE

Filter by status: PLANNED, ACTIVE, CANCELED, COMPLETED; (Default: All values)

origincity
string or null
Example: origincity=Berlin

Search by origincity

destinationcity
string or null
Example: destinationcity=Wolfsburg

Search by destinationcity

username
string or null
Example: username=sergej-stk

Search by username of creator

userid
string or null
Example: userid=d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9

Search by id of creator

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pageable": {
    },
  • "last": true,
  • "totalPages": 0,
  • "totalElements": 0,
  • "first": true,
  • "size": 0,
  • "number": 0,
  • "sort": {
    },
  • "numberOfElements": 0,
  • "empty": true
}

Delete a participant of a ride by user id and ride id [USER, ADMIN]

Delete a participant of a ride by user id and ride id.

Authorizations:
bearerAuth
path Parameters
rideid
required
string <uuid>
userid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Leave a ride [USER ADMIN]

Allows an authenticated user to leave a ride they have joined.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Delete a ride created by authenticated user [USER, ADMIN]

Deletes a ride that belongs to the currently authenticated user based on the provided ride ID.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Authentication Endpoint

Endpoints for user registration and authentication.

User Registration [NONE, USER, ADMIN]

Creates a new user account based on the provided information.

Request Body schema: application/json
required
username
required
string [ 1 .. 100 ] characters

The user's username.

email
required
string [ 1 .. 320 ] characters

The user's email address, used for communication and login.

terms_accepted
required
boolean
password
required
string [ 1 .. 255 ] characters

The user's password, used for login.

lastname
string [ 1 .. 100 ] characters

The user's last name.

firstname
string [ 1 .. 100 ] characters

The user's first name.

Responses

Request samples

Content type
application/json
{
  • "username": "JohnDoe123",
  • "email": "[email protected]",
  • "terms_accepted": true,
  • "password": "your-secret-password",
  • "lastname": "Doe",
  • "firstname": "John"
}

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "role": "USER",
  • "lastname": "Doe",
  • "firstname": "John",
  • "email": "[email protected]",
  • "phonenumber": "+49 170 1234567",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "address": {
    }
}

Password Reset Request [NONE, USER, ADMIN]

Sends a password reset email if the provided email is registered.

Request Body schema: application/json
required
email
required
string [ 1 .. 320 ] characters

The user's email address, used for communication and login.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

Password Reset Confirm [NONE, USER, ADMIN]

Resets password of a user.

Request Body schema: application/json
required
token
required
string

The password token used for password reset requests.

password
required
string [ 1 .. 255 ] characters

The user's password, used for login.

Responses

Request samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiUEFTU1dPUkRfUkVTRVQiLCJzdWIiOiJTZXJnZWpTdGVpbnNpZWtAZ21haWwuY29tIiwiaWF0IjoxNzM5NzM1OTY5LCJleHAiOjE3Mzk3MzY4Njl9.81v1aBWtMcwIMkSDg-Z4ncjdiIMspuGMIaruc0qwloU",
  • "password": "your-secret-password"
}

Response samples

Content type
application/json
{
  • "id": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "username": "JohnDoe123",
  • "role": "USER",
  • "lastname": "Doe",
  • "firstname": "John",
  • "email": "[email protected]",
  • "phonenumber": "+49 170 1234567",
  • "picture": "d9b9c5e2-5d98-4e29-8887-cbe3b2b6a5a9",
  • "address": {
    }
}

User Logout [USER, ADMIN]

User Logout.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2025-04-03T10:00:00Z",
  • "status": 400,
  • "message": "An error occurred while processing the request.",
  • "path": "/api/resource"
}

User Login [NONE, USER, ADMIN]

Authenticates the user based on the provided login credentials.

Request Body schema: application/json
required
email
required
string [ 1 .. 320 ] characters

The user's email address, used for communication and login.

password
required
string [ 1 .. 255 ] characters

The user's password, used for login.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2huRG9lQGV4YW1wbGVtYWlsLmNvbSIsImlhdCI6MTczOTM0MzgzOSwiZXhwIjoxNzM5MzQ3NDM5fQ.TkD-9OSm8EoD5AVTBnWF-ABuh7MQFxbz_sFrgd2XE1A",
  • "token_type": "Bearer",
  • "expires_in": 3600000
}