server RESTful app developed using Spring framework
##Public API
GENERAL NOTES
- Date and DateTime should be in format ISO 8601.
- OrderStatus enumeration contains values : NEW/ACCEPTED/CANCELLED/DONE/WAITING/PROCESSING
- UserType enumeration contains values : CUSTOMER/TAXI_DRIVER
- CarType enumeration contains values : TRUCK/PASSENGER_CAR/MINIBUS
###User API
1. Register
/user/register
RequestType: POST
Request body:
{
"name": "String",
"email" : "String",
"password" : "String",
"mobileNumbers" :[
{"mobileNumber":"String"}
],
"userType" : "UserType",
"car" : {
"manufacturer" : "String",
"model" : "String",
"plateNumber" : "String",
"seatsNumber" : "Integer",
"carType" : "CarType"
},
"driverLicense":{
"code":"String",
"expirationTime":"DateTime"
}
}
NOTES
- If userType is TAXI_DRIVER, car object MUST contain all fields.
- If userType is CUSTOMER, car/driverLicense object will be omitted even if it exists.
2. Recovery password (could be reviewed)
/user/{userId}/password/
RequestType: PUT
Request body:
{
"email" : "String",
"password" : "String"
}
3. Get user profile
/user/{userId}
RequestType: GET
Response:
{
"userId":"String",
"name": "String",
"email" : "String",
"mobileNumbers" : [{
"idMobileNumber":"Integer",
"mobileNumber": "String"
}],
"userType" : "UserType",
"car" : {
"manufacturer" : "String",
"model" : "String",
"plateNumber" : "String",
"seatsNumber" : "Integer",
"carType" : "CarType"
},
"driverLicense":{
"driverLicense":"String",
"expirationTime":"Date"
}
}
4. Update user profile
/user
RequestType: PATCH
Request body:
{
"name": "String",
"mobileNumbers" : [{
"idMobileNumber":"Integer",
"mobileNumber": "String"
}],
"car" : {
"manufacturer" : "String",
"model" : "String",
"plateNumber" : "String",
"seatsNumber" : "Integer",
"carType" : "CarType"
},
"driverLicense":{
"driverLicense":"String",
"expirationTime":"Date"
}
}
NOTES:
- Car and driver license objects will be omitted if userType = CUSTOMER.
- Fields can be omitted because of PATCH function usage
- Exception will be thrown if 'email' field is present (you cannot update your login)
- Exception will be thrown if 'userType' field is present (you cannot change yours role in system)
- If you want to delete mobile number - add it id and set 'mobileNumber' to NULL
- If you want to add mobile number - just set it id to null and fill mobileNumber field
- If you want to update mobile number - just set it id and fill mobileNumber field
- No guarantee that mobile numbers will be added in order they came in request
5. Login
/login
RequestType: POST
Request body:
{
"email":"String",
"password":"String",
"notificationToken":"String"
}
Response body:
{
"token":"String",
"token_type":"String",
"user_type":"String"
}
NOTES:
- notification token is optional field. If present - notification feature will be switched on.
6. Toggle notifications
/user/notifications?toggle=<boolean_value>
RequestType : POST
Request body: absent
NOTES:
- <boolean_value> - true/false;
- if there's no notification token for user - no exception will be thrown;
- if false - no notifications will be sent until switch on
7. Get notification toggle status
/user/notifications/toggle-position
RequestType: GET
Response body: boolean
###Order API 1. Get all orders (by type)
/order?orderStatus='actualOrderStatus'&use-coordinates='boolean'
orderStatus = "OrderStatus" + ALL
Request type: GET
Response:
[{
"orderId" : "Long",
"startTime" : "DateTime",
"startPoint" : "String",
"endPoint" : "String",
"price" : "Double",
"status":"OrderStatus"
}]
NOTES:
- Only a taxi driver is allowed to perform operation
- use-coordinates is optional parameter, default value - false. If true, json structure will be the next:
[{
"orderId" : "Long",
"startTime" : "DateTime",
"startPointCoordinates" : {
"longtitude": "Double",
"latitude" : "Double"
},
"endPointCoordinates" : {
"longtitude": "Double",
"latitude" : "Double"
},
"price" : "Double",
"status":"OrderStatus"
}]
2. Get order with specific id
/order/{orderId}
Request type: GET
Response:
{
"orderId" : "Long",
"startTime" : "DateTime",
"routePoint":[{
"adminArea":"String",
"latitude":"String",
"longtitude":"String",
"street":"String",
"houseNumber":"String",
"city":"String"
}],
"status" : "OrderStatus",
"customerId": "Integer",
"driverId" : "Integer",
"distance": "Double",
"duration":"Time",
"price" : "Double",
"extraPrice":"Double",
"comment":"String",
"additionalRequirements" : [{
"reqId" : "Integer",
"reqValueId":"Integer"
}]
}
NOTES
- taxiDriver can be empty or null if status is NEW.
- If user is a customer, it must be the owner of the order.
3. Add order
/order
Request type: POST
Request body:
{
"startTime" : "DateTime",
"comment" : "String",
"routePoints":[{
"latitude":"String",
"longtitude":"String"
}],
"additionalRequirements" : [{
"reqId" : "Integer",
"reqValueId" : "Integer"
}]
}
NOTES:
- Only customer can perform operation
- if "startTime" is null - quick request. The date of request will be saved and returned by next get request
_4. Change order status _
/order/{orderId}/status
Request type: PATCH
Request body:
{
"orderStatus" : "OrderStatus"
}
NOTES:
- Customer, that not an owner of the order, can't perform this operation.
- Customer-owner of the order can only cancel the order.
- Taxi driver can mark order as done only after accepting its servicing.
- When customer is logged in, specified notification token and driver changes status - notification will be sent to order owner.
- When driver is logged in, specified notification token and customer cancels order - notification will be send to driver.
5. Delete order
/order/{orderId}
Request type: DELETE
NOTES
- Can be performed only by customer-owner.
6. Update order
/order/{orderId}
Request type: PATCH
Request body:
{
"quickRequest":"Boolean",
"startTime" : "DateTime",
"comment":"String",
"routePoint":[{
"routePointId":"Long",
"routePointIndex":"Integer",
"latitude":"String",
"longtitude":"String"
}],
"additionalRequirements" : [{
"reqId" : "Integer",
"reqValueId" : "Integer"
}]
}
NOTES
- if 'quickRequest' is true, 'startTime' will be omitted
- 'orderPrice' can be omitted if there are no changes in additional requirements.
- if there are some changes in additional requirements - add just changed ones.
- 'routePoint' can be omitted if there are no changes in route.
- to remove or change existed route point - add it's 'lat', 'long' and id.
- to add route point to the end of list - omit 'routePointIndex'.
- to add route point to the specific position - fill 'routePointIndex'.
- to remove route point - add it's 'routePointId' and fill 'routePointIndex' to NULL.
- to change route point position - specify its 'routePointIndex'.
- if any route point was update - distance recalculation process will be triggered.
- price recalculation will perform automatically.
- all another params will be ignored.
7. Get order route info
/order/routeinfo
Request type: POST
Request body:
{
"routePoint":{
"latitude":"String",
"longtitude":"String"
},
"additionalRequirements":[{
"reqId" : "Integer",
"reqValueId" : "Integer"
}]
}
Response body:
{
"price":"Double",
"distance":"Double",
"duration":"Time"
}
NOTES
- Can be performed only by customer.
- Duration value format - ISO-8601
##Restore password
Step-by-step:
- /user/password
- Type: POST
- Request body:
{"email":"String"}
- Response body: id of password restore request - restore_id_request
- Result: returned id request that will be used at next request and email message with secret_code
- /user/password/restore_id_request
- Type: POST
- Request body:
{
"password":"String",
"code":"String"
}
GOOGLE CLOUD MESSAGING TEMPLATES
- Change order status notification (for order owner):
- driver is waiting for customer:
{
"data":{
"orderStatus":"WAITING",
"plateNumber":"String",
"model":"String",
"manufacturer":"String",
"name":"String",
"orderId":"Long"
},
"to":"String"
}
- driver/customer changes status
{
"data":{
"orderStatus":"OrderStatus",
"name":"String",
"orderId":"Long"
},
"to":"String"
}
- Add order notification
{
"data":{
"orderId":"Long",
"startPoint":"String",
"endPoint":"String",
"startTime":"price",
"price":"Double"
},
"to":"String"
}
EXCEPTION RESPONSE TEMPLATES
Request validation error template:
[{
"field" : "String",
"code" : "String",
"message" : "String"
}]
Any other exception:
{"message" : "String"}