FIWARE POI-DP GE API v5 Specification

DATE: 2016-08-15
This version:
http://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FIWARE.OpenSpecification.MiWi.POIDataProviderr5
Latest version:
http://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FIWARE.OpenSpecification.MiWi.POIDataProviderlatest

Editors

  1. Ari Okkonen, Adminotech Oy

Copyright 2016 Adminotech Oy

License

This specification is licensed under the [FIWARE Open Specification License] (http://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29).


Abstract

FIWARE Points of Interest Generic Enabler R5

FIWARE POI (Points of interest) Generic Enabler API facilitates

Specially FIWARE POI Generic Enabler API allows you to

Status of this document

Final version of the FIWARE POI DP GE API R5


API Specification

Platform

Get Components

[/get_components]

Get Components

GET /get_components

Return the list of POI data components available from this server.

Parameters
auth_t (required, string)

Authorization token. Not needed, if POI-DP is configured as open data.

Query

Get POIs

[/get_pois]

Get POIs

GET /get_pois

Return the data of POIs listed in the query. This is intended to get additional information - other components - about interesting POIs.

Parameters
auth_t (required, string)

Authorization token. Not needed, if POI-DP is configured as open data.

component (optional, string)

POI data component names to be included to results. Several component names can be given by separating them with commas. If this parameter is not given, all components are included.

get_for_update (optional, boolean)

The components requested are returned with all language and other variants and possible metadata for inspection and edit. Moreover a last_update.timestamp is included to reveal a possible update conflict.

poi_id (required, string)

UUID of the POI. Several UUIDs can be given by separating them with commas.

Update

Update operations should require authorization in order to prevent misuse. The details of the authorization mechanism are out of the scope of this specification.

Add POI

[/add_poi]

Add POI

POST /add_poi

This function is used for adding a new POI entity into a database. The POI data is given as JSON in HTTP POST request. It generates a UUID for the new POI and returns it to the client in JSON format including the timestamp of the POI creation. The client can include different data components to the new POI by sending them along with the request.

The POSTed JSON must include only the content of a single POI, i.e. it must not contain a UUID as key as it is automatically generated by the server.

Parameters
auth_t (required, string)

Authorization token.

poi_id (optional, string)

ID for the new POI.

Update POI

[/update_poi]

Update POI

POST /update_poi

This function is used for updating data of an existing POI entity. Existing data components can be modified or new ones can be added. Each data component contains a last_update.timestamp in order to prevent concurrency issues.

The updated POI data is given as JSON in HTTP POST request. The server responds with HTTP status messages indicating the success or failure of the operation.

Parameters
auth_t (required, string)

Authorization token.

Delete POI

[/delete_poi]

Delete POI

DELETE /delete_poi

Delete existing POI using HTTP DELETE request. The UUID of the POI to be deleted is given in the request as a URL parameter

Parameters
auth_t (required, string)

Authorization token.

id (required, string)

The UUID of the POI to be deleted

Access Control

Log In

[/login]

Log In

POST /login

This function is used for logging in to a POI data provider and obtaining the authorization token for further use.

The auth_p parameter specifies the authentication provider that is used to obtain the identity of the user. The possible values are implementation dependent, e.g.:

  • google - for Google authentication

  • fiware_lab - for FIWARE Lab authentication

The user_id parameter specifies the user_id for the selected account, if multiple user accounts are associated to the authentication.

The content is the authentication token got from the authentication provider.

Parameters
auth_p (required, string)

Authorization provider.

user_id (optional, string)

Needed, if multiple user accounts are associated to the authentication.

Log Out

[/logout]

Log Out

POST /logout

This function is used for finishing the session and to invalidate the authorization token.

Parameters
auth_t (required, string)

Authorization token.

Examples

Update

Add POI

[/add_poi]
Add POI
POST /add_poi
Request /add_poi (application/json)

Headers

Content-Type: application/json

Body

{
  "fw_core": {
    "categories": ["cafe"], 
    "location": {
      "wgs84" { 
        "latitude": 65.059334, 
        "longitude": 25.4664775
      }
    }, 
    "name": {
      "__": "Aulakahvila"
    }
  }
}
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
  "created_poi": {
    "uuid": "6be4752b-fe6f-4c3a-98c1-13e5ccf01721",
    "timestamp": 1394525977
  }
}

Update POI

[/update_poi]
Update POI
POST /update_poi
Request /update_poi (application/json)

Headers

Content-Type: application/json

Body

{ 
  "6be4752b-fe6f-4c3a-98c1-13e5ccf01721": {
    "fw_core": {
      "categories": ["cafe"], 
      "location": {
        "wgs84" { 
          "latitude": 65.059334, 
          "longitude": 25.4664775
        }
      }, 
      "name": {
        "__": "Aulakahvila"
      },
      "description": {
        "__": "Cafe at the Univesity of Oulu"
      },
      "last_update": {
        "timestamp": 1394525977
      }
    }
  }
}
Response 200 (text/plain)

Headers

Content-Type: text/plain

Body

POI data updated succesfully

Access Control

Log In

[/login]
Log In
POST /login
Request /login (text/plain)

Headers

Content-Type: text/plain

Body

rEZhDInMYUVTNCAYyTy7MjXGDYJKR6
Response 200 (application/json)

Headers

Content-Type: application/json

Body

{
  "login":true,
  "auth_t":"1207fbad2f158011dafe594f6db0e7f0e9221a19"
}

References