We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Network Positioning Enabler API Specification - FIWARE Forge Wiki

Network Positioning Enabler API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction

This document serves to give an overview of the Positioning Enabler API and is irrespective of any LBS application, i.e. not application-specific. In the following, the Positioning Enabler Client API specification is presented. Furthermore, an overview of the Positioning Enabler's Network-Messaging API (3rd Party API) is described. Throughout this document, the term "network" is meant to be the specific network a mobile device is connected to (specific Wifi hotspot or specific 4G/3G/2G mobile cell). The position or location of a mobile device is defined as the network the mobile device is connected to (network-based position).

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

Positioning Enabler Services API Core

The Positioning Enabler API has a RESTful architecture, which is resource-oriented and uses HTTP verbs based on JSON representations for information exchange. The API is necessary for the communication of users with the Positioning Enabler Platform, which in turn provides the means for providing LBS to mobile terminal users based on a network-centric positioning as well as a device-centric (out of FI-WARE scope) approach.

The Positioning Enabler API supports the following functionalities :

  • Registration and Authentication (Login/Logout)
  • Subscription/Unsubscription to 3rd Party Services
  • Network-Messaging (Sending messages proactively to a subscriber based on the network, e.g. Wifi hotspot or 3G mobile cell, the subscriber is connected to)
  • Requesting the Network-based Position of a Subscriber
  • Network-based Position Tracking

Intended Audience

This API Specification is intended for developers, Positioning Enabler users as well as 3rd party entities interested in using the Positioning Enabler platform to realize an LBS. Developers can use this API in their applications to integrate network aspects. Moreover, this API can be used by developers to create any type of LBS. For developers, this specification document explains the operations provided by the API. Furthermore, it presents the workflow taking place along with the occurring requests and responses. To use this information the developer is expected to have a general overview of:

  • RESTful Web Services
  • HTTP
  • JSON data format
  • Network-based Services functionality.

For the Positioning Enabler users, this document acts as a high-level manual providing an overview of the API functionality, i.e, what functionality/service does the API provide for the user. Furthermore, the document explains the basic information exchanged with the client for realizing any LBS. The description of the Positioning Enabler's Network-Messaging API (3rd Party API) is intended for network-messaging service users (e.g. providers for the content of specific network-based messages).

In order to use this specifications, the reader is advised to first have a general understanding of the Service, Capability, Connectivity and Control Generic Enabler supporting the Positioning Enabler Platform.

API Change History

This version of the document replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
November 2012
  • Initial Version
  • Architecture Description
December 2012
  • Structure Features of API
  • Requirements Definition
  • Protocols Definition
January 2013
  • Sequence Diagrams
  • Operation Descriptions
April 2013
  • Operations Modifications
May 2013
  • Update based on OpenSpecs Review
  • Resources Summary Update
  • Service Subscription API Operation
  • Operation Examples
June 2013
  • Add API Operations
  • Update operations examples
September 2013
  • New API Operations
  • Update resource summary
  • Add Figures
October 2013
  • Add 3rd Party API operations
  • 3rd Party operations resource summary
  • Operation Examples
  • Figures
January 2014
  • Add user to user network-messaging subscription
  • Add architecture overview
  • Update of REST end points

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see S3C Architecture Description.

General Positioning Enabler Services API Information

Authentication

In the current version there is a basic HTTP authentication at the scope of / for securing the URLs. An app has to put the credentials into the HTTP header within each API call.

Architecture

The following diagram gives an overview about the overall context of the Positioning Enabler.

File:Architecture_Overview.png

REST Resources

Each yellow rectangle represents a single REST API endpoint. Please be aware that there are other active REST API endpoints. However, they are not within the scope of this document.

File:Fiware_REST_URLS_API.png

Representation Format

The Positioning Enabler API supports JSON and form-urlencoded as data serialization format. Therefore, the MIME type has to be application/json or application/x-www-form-urlencoded.

Links and References

There are currently no links or references between resources.

Limits

There are currently no limits except the hardware limit for HTTP connections.

Versions

We maintain one version, which always is the CURRENT status.

Faults

Fault ElementAssociated Error CodesExpected in All Requests?
400 ("Bad Request") The document in the entitybody, if any, contains an error message.YES
404 ("Not Found") The requested URI doesn’t map to any resource.YES
500 ("Internal Server Error") There’s a problem on the server side. The document in the entitybody, if any, is an error message.YES

API Operations

This section presents the operations covered by the Positioning Enabler API. The purpose of each API operation is described. Moreover, a detailed resource description is presented along with the datatype of its representation. Examples of the API operations are also shown.

Client API

Registration & Authentication

Purpose:

Create new user or login an existing user.

HTTP Verb URI Description
GET /login/openid/provider/<provider>/<userId> Redirects to the OpenID login page URL for the selected provider (should be displayed in a browser/browser view). Currently supported provider is ‘Google’

Allows the API user to register to the Positioning Enabler Platform using his Google Email account. Authentication is done using OpenID with Google being the OpenID provider. Therefore, the user is required to have a valid Google account in order to be able to register and authenticate at the PE Platform. <userId> can be a valid user ID from a former login, otherwise it should be ‘null’. In case the user ID suits to the other login credentials, no new user will be created on the database. After a successful browser login, the OpenID provider redirects to the PE for evaluation (GET .../<provider>/<userId>/evaluate). To let the browser/browser view (on the client side) know, that a login was successful or not, the PE redirects to a URI starting with ‘leanengine://’. The client has to look out for that URI and parse it as seen in the examples.

Resource Description

  • Communication
Resource Description: Description of Registration and Authentication

[1]


  • Response
Code Description
200 Request OK
400 Request failed, client failure
404 Provider not found/supported
500 Request failed, server failure

Operation example

The OpenID login does not use JSON Objects (because of the framework used). For that reason the examples are URIs which have to be parsed accordingly.

  • Successful Login

redirects to

‘leanengine://.../?auth_token={authToken}&id={userId}’
  • Error Login

redirects to

‘leanengine://error’

Registration & Authentication via OAuth 2.0

Purpose

Create new user or login an existing user

HTTP Verb URI Description
POST /login/oauth/provider/<provider>/<userId> Login by sending OAuth credentials to the server (after successfully retrieving them on the client side).

Resource Description

  • Communication
Resource Description: Registration and authentification via OAuth 2.0
  • Response
Code Description
200 Request OK
400 Request failed, client failure
500 Request failed, server failure

Operation example

The OpenID login does not use JSON Objects (because of the framework used). For that reason the examples are URIs, which have to be parsed accordingly.

Successful Login

  • Request
POST /login/oauth/provider/google/fd93f9df-67d2-46bd-a363-a31d2ab6e83a HTTP/1.1
Basic cGVfdXNlcjo5NTViMDYzMzY0ZDkxNTdjMDgzOTI1M2U4NDcwMjI2ODliNWVlMWRm
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Host: {serverroot}

{
 "id": "mail@example.com",
 "token": "DQAA......-ia-yRvoTbg",
}
  • Response
HTTP/1.1 200 OK
{
 "id": "fd93f9df-67d2-46bd-a363-a31d2ab6e83a",
 "token": "DQAA......-ia-yRvoTbg",
}

Logout (OpenID and OAuth)

Purpose:

Logout the current user and delete his authentication token regardless of the login method used.

HTTP Verb URI Description
DELETE /logout/openid/user/<userId> Logout on the server

Resource Description

  • Response
Code Description
200 Request OK
400 Request failed, client failure
500 Request failed, server failure

Operation example

Successful Login

  • Request
DELETE /logout/openid/fd93f9df-67d2-46bd-a363-a31d2ab6e83a HTTP/1.1
Basic cGVfdXNlcjo5NTViMDYzMzY0ZDkxNTdjMDgzOTI1M2U4NDcwMjI2ODliNWVlMWRm
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Host: {serverroot}
  • Response
HTTP/1.1 200 OK

Fiware Service Subscription

Purpose

Subscribes/Unsubscribes the user/client to the Fiware service.

HTTP Verb URI Description
POST /user/<userId>/subscription/fiware Subscribes the user to the Fiware service.
DELETE /user/<userId>/subscription/fiware Unsubscribes the user from the Fiware service

Allows the user/client to subscribe to the Fiware service of the Positioning Enabler. If this subscription is successful the user/client is able to subscribe for a specific functionality of the Fiware service, e.g. network-messaging (See chapter "Fiware Network-Messaging Subscription" for more details).

Resource Description

  • Communication
Resource Description: Sequenz diagram for service subscription
  • POST Request

This operation is used to create a new subscription for the user/client to the Fiware service.

  • DELETE Request

This operation is used to delete an existing subscription of the user/client to the Fiware service.

  • Response Code
Code Description
201 Subscription created
204 Subscription deleted
400 Request failed, client failure
500 Request failed, server failure

Operation example

Successful Subscription

  • Request
POST /user/2dbd18ac-20ea-465e-841e-34a76b277637/subscription/fiware HTTP/1.1
Basic cGVfdXNlcjo5NTViMDYzMzY0ZDkxNTdjMDgzOTI1M2U4NDcwMjI2ODliNWVlMWRm
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Host: {serverroot}

{
 “imsi”: ”310260000000000”,
 “mobilePushId”:
                  ”APA91bFji7Pn0LpNj5L1T_n5iwl6jAAursfD3KdKefeqDmILFkNFjnU1-G5II7PMFTTNbT3cgQ5zHjwO2mLZeNGZgWpmOcN_37Sneqq6U3Qv3ZcMb4q9MVCKh8nUryntT0nnt2NsEkBG5UQhfrI3U_eO0hX-eo-yBw”
}
  • Response
HTTP/1.1 200 OK

Unsuccessful Subscription

  • Request
POST /user/xxx/subscription/fiware HTTP/1.1
Basic cGVfdXNlcjo5NTViMDYzMzY0ZDkxNTdjMDgzOTI1M2U4NDcwMjI2ODliNWVlMWRm
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Host: {serverroot}

{
 “imsi”: ”310260000000000”,
 “mobilePushId”:
                  ”APA91bFji7Pn0LpNj5L1T_n5iwl6jAAursfD3KdKefeqDmILFkNFjnU1-G5II7PMFTTNbT3cgQ5zHjwO2mLZeNGZgWpmOcN_37Sneqq6U3Qv3ZcMb4q9MVCKh8nUryntT0nnt2NsEkBG5UQhfrI3U_eO0hX-eo-yBw”
}
  • Response
HTTP/1.1 404
User not found.

Fiware Network-Messaging Subscription

Purpose

Subscribes an user/client for the specific Fiware Service functionality of receiving network-messages either for himself or on behalf of another user.

HTTP Verb URI Description
GET /user/<userId>/usersubscription/<userIdTo> Subscribes for network-messages on behalf of <userIdTo>

<userIdTo> can be either the own userId or another userId. Thus, network-messages will be received based on the network-based position of the user/client or based on the network-position of another user/client. This call initiates the background tracking activity within the Positioning Enabler.

Resource Description

  • Communication
Resource Description: Sequenz diagram for subscription to geo-messaging
  • Response Code
Code Description
200 Request OK
400 Request failed, client failure
404 Request failed, one or both users not found
500 Request failed, server failure

Operation example

  • Request
GET /user/{userIdFrom}/usersubscription/{userIdTo} HTTP/1.1
Accept: application/json
AcceptCharset:UTF-8
Host: {serverroot}
  • Response
GET {serverroot}/user/740568d9-ee22-4483-8f96-c807eb03364a/usersubscription/h432lk432-kj24-6543-1319-c807e213213364a
ContentType: application/json; charset=UTF8
Status Code: 201 CREATED

Position Request

Purpose

Gets the network-based position of the user/client

HTTP Verb URI Description
GET /user/<userId>/position Requests the network-based position of the user/client (Wifi hotspot or 4G/3G/2G mobile cell id).

Allows the user/client to initiate a position request. The request could be either self-referencing (the user plays the role of the consumer and target, i.e. an user/client requests its position) or cross-referencing (the user/client plays the role of the consumer and is not the target, i.e. an user/client requests the position of another user/client).

Resource Description

  • Response
Code Description
200 Request OK
400 Request failed, client failure
500 Request failed, server failure

Operation example

  • Request
GET /user/fd93f9df67d246bda36/position HTTP/1.1
Accept: application/json
AcceptCharset:UTF-8
Host: {serverroot}
  • Response
GET {serverroot}/user/{userId}/position
ContentType: application/json; charset=UTF8
Status Code: 200 OK

{
 "apKey": "Test1#1#FFFE",
 "apName": "4G"
}

3rd Party API

Network-Message Creation

Purpose

Creates a new message and links it to a position entity

HTTP Verb URI Description
POST /service/fiware/notification Posts a new network-message. If network-message creation was successful the server responds with a message id for that network-message.
POST /service/fiware/notification/<messageId> Posts a new or updated network-message. The message id provided by the request is used for that. For resource description see chapter “Network-Message Management”.

Allows the API user to create a new network-message. The URI expects a JSON file whose format is described below. See also the POST method at “Network-Message management”.

Resource Description

  • Communication
Resource Description: Sequence diagram for creating a FI-WARE notification

This is the format expected by the Positioning Enabler server.

{

 "title": "",
 "shortDescription": "",
 "targetAP": ""

}

  • Response Code
Code Description
201 Message created
400 Request failed, client failure
500 Request failed, server failure
Operation example

Creating a Network-Message

  • Request
POST {serverroot}/PositioningEnabler/api/service/fiware/notification HTTP/1.1
Accept: */*
Accept-Charset: UTF-8
Content-Type: application/json; charset=UTF-8
Host: {serverroot}/PositioningEnabler

{
 "title": "Message title",
 "shortDescription": "short",
 "targetAP": "00:80:41:ae:fd:7e"
}
  • Response
Request URL: {serverroot}/PositioningEnabler/api/service/fiware/notification
Request Method: POST
Status Code: 201 Created
Content-Type: text/plain

740568d9-ee22-4483-8f96-c807eb03364a

Network-Message Management

Purpose

Managing an already created network-message given its id. (Updating/Deleting)

HTTP Verb URI Description
GET /service/fiware/<messageId> Retrieves the network-message with the given message id.
POST /service/fiware/<messageId> Updates the network-message with the given message id.
DELETE /service/fiware/<messageId> Deletes the network-message with the given message id.

Allows the service user to manage a specific network-message. The service user can retrieve, update or delete the network-messages. The POST method can also be used to create a new network-message with a given id (this will override the id created by the database).

Resource Description

  • Communication
Resource Description: Management of notifications
  • Response
Code Description
200 Request OK
204 Updated/Deleted
400 Request failed, client failure
500 Request failed, server failure

Operation example

Successful deletion of a network-message

  • Request
DELETE /service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a HTTP/1.1
Accept: */*
Host: {serverroot}
  • Response
Request URL: {serverroot}/service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a
Request Method: DELETE
Status Code: 204 Resource updated

Successful retrieval of a network-message

Request
GET /service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a HTTP/1.1
Accept: application/json; charset=UTF-8
Host: {serverroot}
  • Response
Request URL: {serverroot}/service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a
Request Method: GET
Content-Type: application/json; charset=UTF-8
Status Code: 200 OK

{
 "title": "New message title",
 "shortDescription": "new short",
 "targetAP": "00:80:41:ae:fd:7e"
}

Successful update of a network-message (this would create a network-message with the given id, if it does not exist)

  • Request
POST /service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a HTTP/1.1
Accept: */*
Accept-Charset: UTF-8
Content-Type: application/json; charset=UTF-8
Host: {serverroot}

{
 "title": "New message title",
 "shortDescription": "new short",
 "targetAP": "00:80:41:ae:fd:7e"
}
  • Response
Request URL: {serverroot}/PositioningEnabler/api/service/fiware/notification/740568d9-ee22-4483-8f96-c807eb03364a
Request Method: POST
Status Code: 204 Resource updated
Personal tools
Create a book