Introduction

Dycapo Protocol is an application-level protocol for enabling communication between Dynamic Carpooling servers and clients, using HTTP [RFC2616] and JSON [RFC4627].

Where to start

To better understand OpenTrip Dynamic, you should first read the OpenTrip Core specification, as we are inspiring from it. After that, we may summarize Dycapo Protocol as “OpenTrip entities extended and encoded in JSON”. That is, we took all OpenTrip Core entities as described in the draft, created a convenient UML class diagram for developing Dycapo and extended the entities to suit our needs. That is how Dycapo Protocol is coming out.

Specification

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Each attribute requirement is specified when submitting objects to the system, not when returning them to the clients. Some attributes MAY be hidden when Resources are accessed because of privacy issues, e.g. the actual position of a user. This goes beyond the scopes of this Protocol and depends on the implementation of the server system.

JSON-Related Conventions

Dycapo Protocol Document formats are specified in terms of the JavaScript Object Notation [rfc4627].

Every data type is a JSON data type, as described in JSON specs.

Other Data-Type Conventions

The protocol makes use of GeoRSS Simple Point notation for expressing Geographical coordinates, encapsulated in a JSON string.

Date/Time objects are expressed using JSON string data type, using [ISO 8601] Convention. The following is the preferred format: "YYYY-MM-DD HH:MM:SS", as example: "2010-08-21 21:36:23"

Terminology

For convenience, this protocol can be referred to as the "Dycapo Protocol" or "DycapoP". The following terminology is used by this specification:

Protocol Model

DycapoP specifies operations for publishing, editing and deleting specific Resources using HTTP. It uses JSON-formatted representations to describe the state and metadata of those Resources.

Objects as inner Properties of other Objects

Some DycapoP objects can be obtained as Objects alone or be included in other objects.

As example, a Person object has a location attribute, that holds the current Person position.

When a DycapoP object is returned as an inner property of another object, just the href attribute MUST be included. All the other properties MAY be included.

The href attribute

Each Protocol object MUST include an attribute called href when returned as a resource. The type of this attribute is a string and its value MUST be the URL uniquely identifying the object.

For each Object a URL structure is proposed for sake of comprehension. It SHOULD NOT be followed as it is against REST principles.

The author attribute

Some Protocol objects have an attribute called author. This attribute specifies the Person that created the resource. The requirement of this attribute is always a MAY because its presence depends on the internal implementation of the security systems of the server implementing the protocol. Therefore, its value is usually filled in by the server after an authentication happened.

Initial URI

Dycapo Protocol attempts to be as more REST as possible. Therefore, it defines resources as hypertext driven. Clients SHOULD use an inital URI, here defined as http://example.com/api". Each other access SHOULD be performed using the href attribute of each object.

A GET request to the initial URI should return a list of accessible resources. As example:

{
    "searches": {
        "href": "http://example.com/api/searches/"
    },
    "persons": {
        "href": "http://example.com/api/persons/"
    },
    "trips": {
        "href": "http://example.com/api/trips/"
    }
}

Elements

Location

Represents a single location. See OpenTrip_Core#Location_Constructs for more info.

Attribute Type Requirement
label string MAY
street string MUST*
point string MUST
country string MAY
region string MAY
town string MUST*
postcode number MUST*
subregion string MAY
georss_point string MUST*
offset number SHOULD
recurs string MAY
days string MAY
leaves string (see Dates) MUST
href string MUST NOT

See OpenTrip_Core#Attributes for more info. posi is an extension and is for indicating that the Location represents the current position of a Person.

Data Representation Example

The following is a valid Location object:

{
    "town": "Bolzano",
    "point": "orig",
    "country": "",
    "region": "",
    "subregion": "",
    "days": "",
    "label": "Work",
    "street": "Rom Strasse",
    "postcode": 39100,
    "offset": 150,
    "leaves": "2010-09-02 13:32:34",
    "recurs": "",
    "georss_point": "46.490200 11.342294"
}
Operations
URL http://example.com/persons/[username]/location/
Method GET
Description Returns a Person position


URL http://example.com/persons/[username]/location/
Method POST
Request Body Location
Description Updates (or creates) a Person's position


URL http://example.com/persons/[username]/location/
Method PUT
Request Body Location
Description Updates (or creates) a Person's position


URL http://example.com/trips/[id]/locations/
Method GET
Description Returns the Locations involved in a Trip


URL http://example.com/trips/[trip_id]/locations/[location_id]/
Method GET
Description Returns a Location involved in a Trip

Person

Represents a Person as described on OpenTrip_Core#Person_Constructs

Attribute Type Requirement
username string MUST
email string MUST
first_name string SHOULD
last_name string SHOULD
uri string MAY
phone string SHOULD
location object (Location) MUST NOT
age number SHOULD
gender string SHOULD
smoker boolean MAY
blind boolean SHOULD
deaf boolean SHOULD
dog boolean SHOULD
href string MUST NOT

Data Representation Example

The following is a valid Dycapo Protocol Person:

{
    "username": "driver1",
    "gender": "M",
    "phone": "123456",
    "email": "driver@drivers.com"
}
Operations
URL http://example.com/persons/
Method GET
Description Retrieves a collection of Persons


URL http://example.com/persons/
Method POST
Request Body Person
Description Creates a Person resource


URL http://example.com/persons/[username]/
Method GET
Description Retrieves a Person


URL http://example.com/persons/[username]/
Method PUT
Request Body Person
Description Updates a Person object

Modality

Represents additional information about the mode of transportation being used. See OpenTrip_Core#Mode_Constructs for more info.

 

Attribute Type Requirement
kind string MUST
capacity number MUST
vacancy number MUST
make string MUST
model_name string MUST
year string MAY
color string SHOULD
lic string SHOULD
cost number SHOULD
href string MUST NOT

Data Representation Example

The following is a valid DycapoP Modality object:

{
    "kind": "auto",
    "capacity": 4,
    "lic": "",
    "color": "",
    "make": "Ford",
    "vacancy": 4,
    "cost": 0.0,
    "year": 0,
    "model_name": "Fiesta",
}
Operations
URL http://example.com/trips/[trip_id]/modality/
Method GET
Description Returns the Modality object of that Trip

Preferences

Stores the preferences of a Trip set by the Person who creates it. See OpenTrip_Core#Preference_Constructs for more info. We kept drive and ride attributes just for compatibility reasons: in OpenTrip Dynamic just a driver should be the author of a Trip.

 

Attribute Type Requirement
age string MAY
nonsmoking boolean MAY
gender string MAY
drive boolean MAY
ride boolean MAY
href string MUST NOT

Data Representation Example

The following is a valid DycapoP Prefs object:

{
    "ride": false,
    "gender": "",
    "age": "18-30",
    "drive": false,
    "nonsmoking": false
}
Operations
URL http://example.com/trips/[trip_id]/preferences/
Method GET
Description Returns the Preferences of the Trip

Trip

Represents a Trip. See OpenTrip_Core#Entry_Elements for more info.

 

Attribute Type Requirement
published string (Date) MUST NOT
active boolean MUST
updated string (Date) MUST NOT
expires string (Date) MUST
author object (Person) MAY
locations array (Location) MUST
mode object (Mode) MUST
preferences object (Preferences) MUST
href string MUST NOT
participations array (Participation) MUST NOT


Data Representation Example

The following is a complete DycapoP Trip object, containing the other Entities used as example in the rest of the document

{
    "preferences": {
        "nonsmoking": false,
        "gender": "",
        "ride": false,
        "drive": false,
        "age": "18-30"
    },
    "expires": "2010-09-05 13:33:08",
    "locations": [{
        "town": "Bolzano",
        "point": "orig",
        "country": "",
        "region": "",
        "subregion": "",
        "days": "",
        "label": "Work",
        "street": "Rom Strasse",
        "postcode": 39100,
        "offset": 150,
        "leaves": "2010-09-02 13:32:34",
        "recurs": "",
        "georss_point": "46.490200 11.342294"
    }, {
        "town": "Bolzano",
        "point": "dest",
        "country": "",
        "region": "",
        "subregion": "",
        "days": "",
        "label": "Work",
        "street": "Piazza della Vittoria, 1",
        "postcode": 39100,
        "offset": 150,
        "leaves": "2010-09-02 13:32:34",
        "recurs": "",
        "georss_point": "46.500740 11.345073"
    }],
    "modality": {
        "kind": "auto",
        "capacity": 4,
        "lic": "",
        "color": "",
        "make": "Ford",
        "id": 4,
        "vacancy": 4,
        "cost": 0.0,
        "year": 0,
        "model_name": "Fiesta"
    }
}
Operations
URL http://example.com/trips/
Method GET
Description Retrieves a collection of Trips


URL http://example.com/trips/
Method POST
Request Body Trip
Description Creates a Trip object


URL http://example.com/trips/[trip_id]/
Method GET
Request Body Person
Description Returns a Trip Resource


URL http://example.com/trips/[trip_id]/
Method PUT
Request Body Trip
Description Updates a Trip object


URL http://example.com/trips/[trip_id]/
Method DELETE
Request Body Trip
Description Deletes a Trip object

Participation

Represents a Participation in a Trip.

Attribute Type Requirement
author object (Person) MAY
status string MUST
href string MUST


Data Representation Example

The following is a valid Dycapo Protocol Participation:

{
    "status": "accept",
    "person": {
        "username": "driver1",
        "href": "http://example.com/api/persons/rider1/",
        "location": {
            "href": "http://example.com/api/persons/rider1/location/"
        }
    },
    "href": "http://example.com/api/trips/4/participations/rider1/"
}
Operations
URL http://example.com/trips/[trip_id]/participations/
Method GET
Description Retrieves the Participations of the Trip


URL http://example.com/trips/[trip_id]/participations/
Method POST
Request Body Participation
Description Creates a Participation object related to the Trip (Requesting a Ride)


URL http://example.com/trips/[trip_id]/participations/[username]/
Method PUT
Request Body Person
Description Updates a Participation object related to the Trip (Accepting a Ride request, Starting a Ride, Finishing a Ride)


URL http://example.com/trips/[trip_id]/participations/[username]/
Method DELETE
Description Deletes a Participation resource (Refusing a Ride request, Deleting a Ride request).

Search

This resource represents a search between Trips. Due to the complexity of the objects involved when searching a Trip, there is the necessity of creating state-ful Search objects, accessible each time a search is needed.

Attribute Type Requirement
origin object (Location) MUST
destination object (Location) MUST
author object (Person) MAY
trips array (Trip) MUST NOT
Data Representation Example

The following is a valid Search object:

{
    "origin": {
        "town": "Bolzano",
        "point": "posi",
        "href": "http://example.com/api/searches/37/",
        "country": "",
        "region": "",
        "subregion": "",
        "days": "",
        "label": "Work",
        "street": "Drususallee, 43/a",
        "postcode": 39100,
        "offset": 150,
        "id": 140,
        "leaves": "2010-09-02 13:32:34",
        "recurs": "",
        "georss_point": "46.494957  11.340239"
    },
    "author": {
        "username": "rider1",
        "href": "http://example.com/api/persons/rider1/"
    },
    "destination": {
        "town": "Bolzano",
        "point": "dest",
        "href": "http://example.com/api/searches/37/",
        "country": "",
        "region": "",
        "subregion": "",
        "days": "",
        "label": "Work",
        "street": "Piazza della Vittoria, 1",
        "postcode": 39100,
        "offset": 150,
        "id": 141,
        "leaves": "2010-09-02 13:32:34",
        "recurs": "",
        "georss_point": "46.500891  11.344306"
    }
}
Operations
URL http://example.com/searches/
Method POST
Request Body Search
Description Creates a Search object


URL http://example.com/searches/[search_id]/
Method GET
Description Retrieves the Search object and the results, if any

Use of HTTP Response Codes

The Dycapo Protocol uses the response status codes defined in HTTP to indicate the success or failure of an operation. Consult the HTTP specification [RFC2616] for detailed definitions of each status code. In detail, DycapoP makes use of the following codes:

Code Name Description
200 OK Denotes a successful operation, an entity containing additional information SHOULD be provided
201 Created Denotes the creation of a resource. A representation of the Resource SHOULD be provided
204 No Content Denotes the deletion of a resource. A representation of the Resource SHOULD NOT be provided
401 Unauthorized The client provided wrong (or did not provide) credentials
403 Forbidden The client does not have the rights for perform the request
404 Not Found No Resource has been found at the given URI
415 Unsupported Media Type A Protocol Error Occurred. A description of the error SHOULD be provided