Travel App

Table of Contents

• Changelog
• 1. Login
• 2. Get itineraries
• 3. Delete itinerary
• 4. Get user itinerary
• 5. Add destination
• 6. Delete destination
• 7. Update destination
• Glossary

Changelog

Version	Date	Author	Description
1.0	13-Mar-2023	Justin Tan	Initial draft

1. Login

Authenticate the user with the system and obtain the auth_token

Request

Method	URL
POST	api/#/

Type	Params	Values
HEAD	api_key	string
POST	username	string
POST	password	string

api_key

Must be sent with all client requests. The api_key helps the server to validate the request source.

Response

Status	Response
200	{ "auth_key": <auth_key> } auth_key (string) - all further API calls must have this key in header
403	{"error":"API key is missing."}
400	{"error":"Please provide username."}
400	{"error":"Please provide password."}
401	{"error":"Invalid API key."}
401	{"error":"Incorrect username or password."}
500	{"error":"Something went wrong. Please try again later."}

2. Get itineraries

Get all itineraries.

Request

Method	URL
GET	itineraries

Type	Params	Values
HEAD	auth_key	string

auth_key

The auth_key that was given in response to /api/#

Response

Status	Response
200	Response will be an object containing the list of itineraries (array). Each item in the array has the following structure. { "id": 1, "user_id": 10, "destination_city": "Perth", "destination_country": "Australia", "destination_start_date": 2023-06-01, "destination_end_date": 2023-06-11, "budget": 3.50, "transport_id": 1, "accomodation_id": 3 } An example response is:- { "itineraries": [ { "id": 1, "user_id": 10, "destination_city": "Perth", "destination_country": "Australia", "destination_start_date": 2023-06-01, "destination_end_date": 2023-06-11, "budget": 3.50, "transport_id": 1, "accomodation_id": 3 } ] }
401	{"error":"Invalid API key."}
500	{"error":"Something went wrong. Please try again later."}

3. Delete itinerary

Delete all itinerary items for the user id.

Request

Method	URL
DELETE	itinerary/{userId}

Type	Params	Values
HEAD	auth_key	String

auth_key

The auth_key that was given in response to /api/#

Response

Status	Response
204	Empty body
401	{"error":"Invalid Auth key."}
500	{"error":"Something went wrong. Please try again later."}

4. Get user itinerary

Gets the itinerary for the specified userId.

Request

Method	URL
GET	itineraries/{userId}

Type	Params	Values
HEAD	auth_key	string

auth_key

The auth_key that was given in response to /api/#

Response {#response}

Status	Response
200	Response will be an object containing the itinerary with user_id = userId. An example response is:- { "id": 1, "user_id": 10, "destination_city": "Perth", "destination_country": "Australia", "destination_start_date": 01/06/2023, "destination_end_date": 08/06/2023, "budget": 3.50, "transport_id": 1, "accomodation_id": 3 }
401	{"error":"Invalid API key."}
500	{"error":"Something went wrong. Please try again later."}

5. Add destination

Add an item to the itinerary for the specified userId.

Request

Method	URL
POST	itineraries/{userId}

Type	Params	Values
HEAD POST	auth_key destinationCity	string string

auth_key

The auth_key that was given in response to /api/#

destinationCity

The destination city to be deleted.

Body

Type	Content
application/json	Content will be an object containing the new itinerary item, sans userId and id. Example content:- { "destination_city": "Perth", "destination_country": "Australia", "destination_start_date": 01/06/2023, "destination_end_date": 08/06/2023, "budget": 3.50, "transport_id": 1, "accomodation_id": 3 }

Response

Status	Response
200	The ID of the created itinerary. Example response:- {"itinerary":10}
401	{"error":"Invalid API key."}
500	{"error":"Something went wrong. Please try again later."}

6. Delete destination

Delete itinerary record with the itineraryId for the specified userId.

Request

Method	URL
DELETE	itineraries/{userId}/{itineraryId}

Type	Params	Values
HEAD	auth_key	string

auth_key

The auth_key that was given in response to /api/#

destinationCity

The destination city to be deleted.

Response

Status	Response
204	Empty Body
401	{"error":"Invalid API key."}
500	{"error":"Something went wrong. Please try again later."}

7. Update destination

Update itinerary records with the itineraryId for the specified userId.

Request {#request}

Method	URL
PUT	itineraries/{userId}/{itineraryId}

Type	Params	Values
HEAD	auth_key	string

auth_key

The auth_key that was given in response to /api/#

Body

Type	Content
application/json	Content will be an object containing the updated itinerary item, sans userId and id. Example content:- { "destination_city": "Perth", "destination_country": "Australia", "destination_start_date": 01/06/2023, "destination_end_date": 08/06/2023, "budget": 3.50, "transport_id": 1, "accomodation_id": 3 }

Response

Status	Response
200	The ID of the updated itinerary. Example response:- {"itinerary":10}
401	{"error":"Invalid API key."}
500	{"error":"Something went wrong. Please try again later."}

Glossary

Conventions

• Client - Client application.
• Status - HTTP status code of response.
• All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
• All response are in JSON format.
• All request parameters are mandatory unless explicitly marked as [optional]
• The type of values accepted for a request parameter are shown the the values column like this [10|<any number>] .The | symbol means OR. If the parameter is [optional], the default value is shown in blue bold text, as 10 is written in [10|<any number>].

Status Codes {#status-codes}

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred in client’s part

5XX - Error occurred in server’s part

Status Code	Description
200	OK
201	Created
202	Accepted (Request accepted, and queued for execution)
400	Bad request
401	Authentication failure
403	Forbidden
404	Resource not found
405	Method Not Allowed
409	Conflict
412	Precondition Failed
413	Request Entity Too Large
500	Internal Server Error
501	Not Implemented
503	Service Unavailable