Skip to content

Social Routing API

baltasarb edited this page Jul 27, 2019 · 14 revisions

Social Routing API

Description

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

Table of contents

Overview

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

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

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: 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

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

  • 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

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.