Social Routing API

Social Routing API

Description

This page describes the Social Routing service API functionalities and specifications.

Table of contents

• Overview
• Persons
• Routes

Overview

• Schema
• Authentication
• Parameters
• Errors
• HTTP Verbs
• Hypermedia
• Pagination

Schema

All API access is done over HTTP and accessed from http://api.sr. All the API data is sent and received in the JSON format. The root endpoint of the API gives information about the available API endpoints.

Summary Representation

A collection of resources will contain a summary version of each resource - a resource without all of its attributes. This happens to avoid performance problems when fetching a collection of resources that each contain many attributes. To fetch all the attributes of a resource a detailed representation must be fetched.

For example, a collection of summary representations of routes will be received in the following request: /api.sr/routes.

Example of a collection of resources, being that each collection element is in it's summary resource representation, when requesting the routes of a user:

{
    "routes": [
        {
            "identifier": 1,
            "name": "route 1",
            "rating": 1,
            "imageReference": "image reference 1",
            "route_url": "http://host/api.sr/routes/1"
        },
        {
            "identifier": 2,
            "name": "route 2",
            "rating": 1,
            "imageReference": "image reference 2",
            "route_url": "http://host/api.sr/routes/2"
        }
    ]
}

Detailed Representation

When an individual resource is fetched the response contains all the attributes for that resource. The following request receives a response with a detailed representation: /api.sr/routes/1. An example of a of a detailed resource, when requesting a single route:

{
    "identifier": 1,
    "location": "location 1",
    "name": "route name",
    "description": "route description",
    "rating": 1,
    "duration": "short",
    "dateCreated": "2019-05-30",
    "points": [
        {
            "latitude": 3,
            "longitude": 1
        }
    ],
    "categories": [
        {
            "name": "sea"
        },
        {
            "name": "sports"
        }
    ],
    "pointsOfInterest": [
        {
            "identifier": "point of interest 1",
            "latitude": 1,
            "longitude": 1
        },
        {
            "identifier": "point of interest 2",
            "latitude": 2,
            "longitude": 2
        }
    ],
    "ordered": false,
    "circular": false,
    "imageReference": "image reference",
    "owner_url": "http://host/api.sr/persons/1"
}

Authentication

The authentication has two different endpoints, one to obtain credentials to access the API and the other to refresh the already obtained credentials. To make an authenticated request to the API the user must make every request with the already obtained access token in the Authorization header of the request.

Obtaining credentials

To obtain API credentials a POST [26] request must be made to the endpoint: http://host/api.sr/auhtentication/google, with the id token string in the body of the request:

{ 
  "idTokenString" : "id token string" 
} 

The request to this endpoint receives a response containing all the necessary data to make authenticated requests to the API. An example response:

{ 
  "accessToken": "access token 1", 
  "refreshToken": "refresh token 1" 
}

Refreshing the credentials

To refresh credentials a POST request must be made to the endpoint: http://api.sr/auhtentication/refresh containing in it’s body the refresh token. If the refresh token is valid a response with a new access token and refresh token is generated.

Errors

• Error response structure
• Error types
• Error instances

An error response follows the standard from RFC that can be found here

There are x type of errors that the API can respond with.

Structure of an error response:

"error": {
    "type": "(string) A URI reference [RFC3986] that identifies the
      problem type.  This specification encourages that, when
      dereferenced, it provide human-readable documentation for the
      problem type (e.g., using HTML [W3C.REC-html5-20141028]).  When
      this member is not present, its value is assumed to be
      'about:blank'.",

    "title": "(string)A short, human-readable summary of the problem
      type.  It SHOULD NOT change from occurrence to occurrence of the
      problem.",

    "status": "(number) The HTTP status code ([RFC7231], Section 6)
      generated by the origin server for this occurrence of the problem",

    "detail": "(string) A human-readable explanation specific to this
      occurrence of the problem.",

    "instance" : "(string) A URI reference that identifies the specific
      occurrence of the problem.",
}

Error types

• Unsupported media type
• Bad Request
• Not Found
• Google Token Invalid
• Authorization Header
• Invalid Refresh Token
• Refresh Not Allowed
• Token Expired
• Invalid Access Token
• Media Type Not Present
• Invalid Route Search Parameter
• Internal Server Error
• Forbidden Request
• Route Categories Required

Unsupported media type

Status : 415
Reason: the current version of the API only allows requests with the application/json content type headers.

Bad Request

Status : 400
Reason: The request is missing one or more required fields or parameters and as such is poorly formed.

Not Found

Status : 404
Reason: The requested resource does not exist.

Google Token Invalid

Status: 401 Reason: The provided google authentication token is not valid.

Authorization Header

Status: 400 Reason: The Authorization header is missing from the request headers.

Invalid Refresh Token

Status: 401 Reason: The refresh token provided either does not exist or is no longer valid.

Refresh Not Allowed

Status: 401 Reason: The refresh token provided still haves a valid access token and as such cannot be renewed.

Token Expired

Status: 401 Reason: The access token provided is expired and should be renewed.

Invalid Access Token

Status: 401 Reason: The access token provided is either expired or invalid.

Media Type Not Present

Status: 400 Reason: The required media type is not present in the request headers.

Invalid Route Search Parameter

Status: 400 Reason: The request is poorly formed or is missing a required parameter.

Internal Server Error

Status: 500 Reason: Something went wrong.

Forbidden Request

Status: 403 Reason: The request maker does not have permission to make such request.

Route Categories Required

Status: 400 Reason: The request was made without specifying at least one category.

HTTP Verbs

Verb	Description
GET	Used for retrieving resources.
POST	Used for creating resources.
PUT	Used for replacing resources.
DELETE	Used for deleting resources.

GET Example

Used to retrieve a resource, an example GET request is the following:

GET http://api.sr/routes/1

This requests the route resource with the identifier 1. Response:

{
    "identifier": 3,
    "location": "Test 2",
    "name": "route",
    "description": "route description",
    "rating": 1,
    "duration": "short",
    "dateCreated": "2019-07-14",
    "points": [
        {
            "latitude": 3,
            "longitude": 1
        }
    ],
    "categories": [
        {
            "name": "sea"
        },
        {
            "name": "sports"
        }
    ],
    "pointsOfInterest": [
        {
            "identifier": "point of interest 1",
            "latitude": 1,
            "longitude": 1
        },
        {
            "identifier": "point of interest 2",
            "latitude": 2,
            "longitude": 2
        }
    ],
    "ordered": false,
    "circular": false,
    "imageReference": "abc",
    "owner_url": "http://localhost:8080/api.sr/persons/100"
}

POST Example

The POST HTTP method is used to create resources. It requires that the Content-Type HTTP header is defined and with the value application/json. The following request creates a route owned by the person with identifier 1.

POST http://api.sr/routes

And in the body of the request, the route to be created must be described:

{
	"location": "location 1",
	"name": "name 1",
	"description": "description 1",
	"personIdentifier": 1,
	"points": [
		{
			"latitude":1.2,
			"longitude":1.2
		},
		{
			"latitude":1.3,
			"longitude":1.4
		}
	],
	"categories" : [
		{
			"name" : "Sea"
		},
		{
			"name" : "Sports"
		}
	],
	"isCircular" : false,
	"isOrdered": true,
	"pointsOfInterest" : [
		{
			"identifier" : "point of interest identifier 1",
			"latitude": 1,
			"longitude":1
		},
		{
			"identifier" : "point of interest identifier 2",
			"latitude": 2,
			"longitude":2
		}
	],
	"imageReference":"image reference 1",
	"duration": 1
}

The response to this request will have an empty body and return the location of the created resource in the Location header of the response. If successful the status code of the response is 201.

PUT Example

The PUT method is used to replace or update a resource or a collection of resources. Like the post request it requires that the request contains the HTTP header Content-Type defined with application/json.
The following request replaces the currently existing resource route with identifier 1 with the one sent in the body of the request.

PUT http://api.sr/routes/1

{
	"location": "location 1",
	"name": "route name 1",
	"description": "route description 1",
	"rating": 1.0,
	"duration": "short",
	"ordered":false,
	"circular":true,
	"imageReference":"image reference 1",
	"points":[
		{
		  "latitude": 3.0,
		  "longitude": 1.0
		}
	],
	"categories":[
		{
			"name":"Sports"
		},
		{
			"name":"Sea"
		}
	]
}

A successful response will have the 200 OK status and an empty body.

DELETE Example

The following example illustrates the deletion of a route resource with the identifier 1.

DELETE http://api.sr/routes/1

The response, if successful, contains an empty body and the status code 200.

Hypermedia

Some resources will have links to other resources. Either to a parent resource or to a detailed representation of a resource within a collection.

For example, a user resource might have a link to their created routes, which holds a collection of routes. That same collection might have a link to the profile of the person who created the routes.

The API root page provides the available URLs in the API:

{
    "person_url": "http://10.0.2.2:8080/api.sr/persons/{personIdentifier}",
    "route_search_url": "http://10.0.2.2:8080/api.sr/routes/search?{params}",
    "categories_url": "http://10.0.2.2:8080/api.sr/categories",
    "authentication_urls": {
        "google": "http://10.0.2.2:8080/api.sr/authentication/google"
    },
    "documentation_url": "https://github.com/baltasarb/social-routing/wiki/Social-Routing-API"
}

The following diagram shows the API hypermedia relations:

Pagination

Requests that return a collection of resources will be paginated to a default value of 10 resources and page number equal to 1. A specific page can be requested with the query parameter ?page={number}.

Persons

• Get Person
• Create Person
• Update Person
• Delete Person
• Get a person's routes

Get Person

Request

The following request retrieves the person with the identifier 1.

HTTP method: GET.
URL: http://api.sr/persons/{personIdentifier}.

Response

Status: 200 Ok.

Example:

{
    "identifier": 1,
    "rating": 1,
    "routes_url": "http://localhost:8080/api.sr/persons/1/routes"
}

Update Person

• Request
• Response

Request

• HTTP method: PUT.
• URL: http://api.sr/persons/{personId}.

Headers

• Content-Type: application/json.

Body

Name	Type	Description
rating	double	Required. The new rating of the person.

Example

{
  "rating": 5.0,
}

Response

Status: 200 when successful.

Delete Person

Request

HTTP method: DELETE.
URL: http://api.sr/persons/{personId}. |

Response

Status: 200 when successful.

Get a person's routes

Request

URL: http://api.sr/persons/{personId}/routes.

Response

Status: 200 Ok.

Example

{
    "routes": [
        {
            "identifier": 1,
            "name": "route 1",
            "rating": 1,
            "imageReference": "image reference 1",
            "route_url": "http://api.sr/routes/1"
        },
        {
            "identifier": 2,
            "name": "route 2",
            "rating": 1,
            "imageReference": "image reference 2",
            "route_url": "http://api.sr/routes/2"
        }
    ]
}

Routes

• Get Route
• Create Route
• Update Route
• Delete Route
• Search Route By Geographic Location
• Search Route By A User's Geographic Location

Get Route

Request

Http method: GET.
URL: http://api.sr/routes/{routeIdentifier}.

Response

Status: 200 Ok.

Example

GET http://api.sr/routes/1

Retrieves the route with identifier 1.

{
    "identifier": 1,
    "location": "location 1",
    "name": "route name 1",
    "description": "route description 1",
    "rating": 1.0,
    "duration": "short",
    "dateCreated": "2019-05-14",
    "points": [
        {
            "latitude": 3.0,
            "longitude": 1.0
        }
    ],
    "categories": [
        {
            "name": "sea"
        },
        {
            "name": "sports"
        }
    ],
    "pointsOfInterest": [
        {
            "identifier": "point of interest 1",
            "latitude": 1.0,
            "longitude": 1.0
        },
        {
            "identifier": "point of interest 2",
            "latitude": 2.0,
            "longitude": 2.0
        }
    ],
    "ordered": false,
    "circular": false,
    "imageReference": "abc",
    "owner_url": "http://localhost:8080/api.sr/persons/1"
}

Create Route

Request

• HTTP method: POST.
• URL: http://api.sr/routes.

Headers

• Content-Type: application/json.

Body

Name	Type	Description
location	string	Required. The route's location.
name	string	Required. The route's name.
description	string	Required. The route's description.
points	object array	Required. An array of objects, with each object containing the fields latitude and longitude, with corresponding values of the double type. The coordinates that compose the route.
categories	object array	Required. Array of objects, with each containing a field name, of type string with the name of an existing application category.
isCircular	boolean	Required. Information regarding the route's structure, if it starts at the same place where it begins. True if yes, false if not.
isOrdered	boolean	Required. Information about the starting place of the route. If it's true then only the first route point is considered as a starting point. If false the last point is also considered.
pointsOfInterest	object array	Optional. Route geographical points of interest. Each object within the array must contain its geographic coordinates (latitude and longitude of type double) and the name of the point of interest of type string.
imageReference	string	Required. A reference to the image in the google platform where an image URL can be retrieved to represent this route's cover image.
ownerUrl	string	Required. URL to the route owner.

Example

{
	"location": "location 1",
	"name": "name 1",
	"description": "description 1",
	"personIdentifier": 100,
	"points": [
		{
			"latitude":1.2,
			"longitude":1.2
		},
		{
			"latitude":1.3,
			"longitude":1.4
		}
	],
	"categories" : [
		{
			"name" : "Sea"
		},
		{
			"name" : "Sports"
		}
	],
	"isCircular" : false,
	"isOrdered": true,
	"pointsOfInterest" : [
		{
			"identifier" : "point of interest 1",
			"latitude": 1,
			"longitude":1
		},
		{
			"identifier" : "point of interest 2",
			"latitude": 2,
			"longitude":2
		}
	],
	"imageReference":"image reference 1",
	"duration": 1
}

Response

Status: `201 Created`
Location: http://api.sr/persons/{personIdentifier}

Update Route

Request

• HTTP method: PUT.
• URL: http://api.sr/routes/{routeIdentifier}.

Headers

• Content-Type: application/json.

Body

Name	Type	Description
location	string	Required. The route's location.
name	string	Required. The route's name.
description	string	Required. The route's description.
points	object array	Required. An array of objects, with each object containing the fields latitude and longitude, with corresponding values of the double type. The coordinates that compose the route.
categories	object array	Required. Array of objects, with each containing a field name, of type string with the name of an existing application category.
isCircular	boolean	Required. Information regarding the route's structure, if it starts at the same place where it begins. True if yes, false if not.
isOrdered	boolean	Required. Information about the starting place of the route. If it's true then only the first route point is considered as a starting point. If false the last point is also considered.
pointsOfInterest	object array	Optional. Route geographical points of interest. Each object within the array must contain its geographic coordinates (latitude and longitude of type double) and the name of the point of interest of type string.
imageReference	string	Required. A reference to the image in the google platform where an image URL can be retrieved to represent this route's cover image.
ownerUrl	string	Required. URL to the route owner.
rating	double	Required. The route's new rating.
duration	string	Required. The route's new duration.

Example

{
	"location": "location 1",
	"name": "name 1",
	"description": "description 1",
	"personIdentifier": 1,
	"points": [
		{
			"latitude":1.2,
			"longitude":1.2
		},
		{
			"latitude":1.3,
			"longitude":1.4
		}
	],
	"categories" : [
		{
			"name" : "Sea"
		},
		{
			"name" : "Sports"
		}
	],
	"isCircular" : false,
	"isOrdered": true,
	"pointsOfInterest" : [
		{
			"identifier" : "point of interest 1",
			"latitude": 1,
			"longitude":1
		},
		{
			"identifier" : "point of interest 2",
			"latitude": 2,
			"longitude":2
		}
	],
	"imageReference":"image reference 1",
	"duration": "long",
  "rating":2.0
}

Delete Route

Request

HTTP method: DELETE.
URL: http://api.sr/routes/{routeIdentifier}. |

Response

Status: 200 OK.

Search Route By Geographic Location

Request

Http method: GET. URL: http://api.sr/routes.

Response

Status: 200 OK.

Example

GET http://api.sr/routes/search?location=location1&page=1&categories=Sea,Sports&duration=Short

{
    "routes": [
        {
            "identifier": 1,
            "name": "route 1",
            "rating": 1.0,
            "imageReference": "image reference 1",
            "route_url": "http://api.sr/routes/1"
        },
        {
            "identifier": 2,
            "name": "route 2",
            "rating": 1.0,
            "imageReference": "image reference 2",
            "route_url": "http://api.sr/routes/2"
        }
    ]
}

Query Parameters

Name	Type	Description
location	string	Required. The desired location's identifier in the google platform.
category	string	Required. Can be many of Sea, Nature, Urban, Culture, Sports. At least one category is required when searching a route.
duration	string	Required. The duration of a route. It can be Short, Medium or Long.
page	int	Optional. The desired collection page. If no value is provided then the page one is selected by default.

Search Route By A User's Geographic Location

Request

Http method: GET. URL: http://api.sr/routes.

Response

Status: 200 OK.

Example

GET http:/api.sr/routes/search?page=1&latitude=32.1&longitude=33.4&location=location1&categories=Sea,Sports&duration=Short

{
    "routes": [
        {
            "identifier": 1,
            "name": "route 1",
            "rating": 1.0,
            "imageReference": "image reference 1",
            "route_url": "http://api.sr/routes/1"
        },
        {
            "identifier": 2,
            "name": "route 2",
            "rating": 1.0,
            "imageReference": "image reference 2",
            "route_url": "http://api.sr/routes/2"
        }
    ]
}

Query Parameters

Name	Type	Description
location	string	Required. The identifier of the user's location in the google platform.
category	string	Required. Can be many of Sea, Nature, Urban, Culture, Sports. At least one category is required when searching a route.
duration	string	Required. The duration of a route. It can be Short, Medium or Long.
page	int	Optional. The desired collection page. If no value is provided then the page one is selected by default.
latitude	double	Required. The latitude of the user's geographic location.
longitude	double	Required. The longitude of the user's geographic location.