Interface meeting RequestStops

Interface Meeting (09.06.2016)

• Author: @themetalone

• Reviewer: @GSE-Project/group1 @GSE-Project/group3

• Review-Status: none yet

Abstract

During this meeting all 3 groups agreed on interface additions for the next two iterations. Systemfunktion C4 is removed from the requirements as it has no relevance to the use cases. Interfaces to handle stop requests have been designed.

Anotation

The usage of {} in URLs symolizes passed data. i.e.http://host/data?x={y} would be passed as http://host/data?x=a when the clients y value is equal to a.

Use case refinement: How to request a custom stop

1. Citizen requests a custom stop at the server

2. Server answers to the Citizen with the assigned request id

3. Server calculates the responsible bus and notifies the driver

4. Driver accepts or rejects the request

5. Citizen asks for the state of the request at random.

6. When picking up the Citizen the Driver marks the request as complete

JSON interfaces

POST Custom Stop Request Citizen → Server /CustomStops

{
	"lineId": "number",
	"pickUpTime": "number <1>",
	"location": "GeoJSONPoint <2>",
	"numberOfPersons": "number",
	"deviceID": "string <3>",
	"info": {
		"name": "string",
		"address": "string <4>",
		"assistance": ["number <5>"]
	}
}

1. Although a fixed point in time is specified, the pickUpTime represents a time intervall. It’s length has yet to be agreed upon.

2. The determination of the location is up to Group 2

3. Should be unique and invariant under application/device restarts

4. Important to the driver

5. The assistance is coded via numbers, e.g: "wheelchair" → 1, "Help with luggage" → 2 and so on. The exact list is to be published on the server github wiki. The list is binding to all groups

GET Status of a Request Citizen → Server /CustomStops?id={request_id}&deviceId={device_id}

{
	"id": "number",
	"deviceId": "string",
	"state": "number <1>"
}

1. The state is coded via numbers. The exact list is to be published on the server github wiki. The list is binding to all groups. The current list is contains pending, accepted, rejected, completed, notshownup and may be subject to changes.

Interfaces needed but not agreed upon yet

The following interfaces weren’t defined during the meeting but the groups agreed upon that those interfaces need to be specified. Since they always concern only two groups at once the definition of those is up to the concerned groups.

• Response during Request POST Citizen → Server (should contain request_id)

• Request GET Driver → Server (should contain most of the already defined request interface)

• RequestState POST Driver → Server

Technical Aspects

Driver

• GET request

  • Request would be done in an interval. next step would be push notification

  • First Step: http://CustomStops/{lineId}

  • Second Step: http://CustomStops?lineId={lineId}

  • Driver would get a list of customStopObject

  • Every custom stop would have an unique ID

States during a Request (Specialization)

• citizen has asked for a stop

  • driver can see the list of stops and can send a update request for each of them

    • accept → POST http://host/CustomStops/{id} with status={accepted}

    • reject → POST http://host/CustomStops/{id} with status={rejected}

• citizen checks the status

  • gets

    • accepted

    • rejected

• driver picks up the citizen

  • updates the request to completed

Other Topics discussed

• We agreed upon changes in /busses and busses/{id}

  • The Bus object contains now totalSeats

  • The RealTimeBusData conatins now takenSeats

  • Changes are already applied to the interface document

• Changes in /stops

  • the schedule objects can now contain id properties