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
FIWARE.OpenSpecification.Apps.RSSRest - FIWARE Forge Wiki

FIWARE.OpenSpecification.Apps.RSSRest

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the RSS API

  • Copyright © 2013 - 2014 by Telefónica I+D. All Rights Reserved.
  • Copyright © 2015 by UPM


RSS API Core

The RSS GE offers a series of RESTful API: it is resource oriented, accessed via HTTP and using XML or JSON representation for information interchange depending on the case.

The RSS GE API allows:

  • Other components to send charging information to the RSS GE.
  • To manage RS Models (Revenue Sharing models) for providers.
  • To create expenditure limits for providers and customers.
  • To control that customers do not overpass the expenditure limits previously created.

Intended Audience

This specification is intended for both software developers and implementers of the FI-WARE Business Framework. For the former, this document provides a full specification of how to interoperate with products that implement the RSS APIs. For the latter, this specification indicates the interface to be implemented and provided to clients.

In order to use this specification, the reader should firstly have a general understanding of the RSS Enabler. You should also be familiar with:

  • RESTful web services.
  • HTTP/1.1.
  • XML data serialization formats.
  • W3C WS-*.

API Change History

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


Revision Date Changes Summary
Apr 09, 2013
  • Initial version
Jan 30, 2014
  • Add New API functionality
Ago 04, 2014
  • Add RS Models API functionality

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 RSS Enabler.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website at RSS API . For more details about the RSS GE that this API is based upon, please refer to the High Level Description. Related documents, including an Architectural Description, are available at the same site.

General RSS API Information

Resources Summary


Authentication

Each HTTP request against the RSS GE requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token, etc.) and will be determined by the specific provider that implements the GE. Please contact with them to determine the best way to authenticate against this API. Some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Representation Format

The RSS API supports XML and JSON for delivering metadata resources. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header (application/xml) or (application/json).

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.


Resource Identification

In order to identify unambiguously the resources, for HTTP transport is used the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616 (http://www.w3.org/Protocols/rfc2616/rfc2616.html).

Links and References

Web citizen

The RSS GE is relying on Web principles:

  • URI to identify resources
  • consistent URI structure based on REST style protocol

Paginated Collections

The RSS API will not limit the number of elements returned, because RSS services don't require the exchange of large data sets.

API Operations

The following sections explain the generic API operations. For complete examples of API requests and responses you can refer to the User's and Programmers Guide manual at https://forge.fi-ware.org/plugins/mediawiki/wiki/fiware/index.php/RSS_-_User_and_Programmer_Guide

RSS API REST

Processing RSS Information

Creating RSS entries from CDRs

This API exposes the functionality that a partner (usually a store) will use to send its CDRs (Charging Data Record) to the RSS enabler for their processing.

Verb URI Description
POST /rss/cdrs Process one or more CDRs resources received


This API is related to the method detailed in https://forge.fi-ware.org/plugins/mediawiki/wiki/fiware/index.php/FIWARE.OpenSpecification.Apps.RSS#Receiving_CDRs

Request Body

The request body of a POST operation should contain either the full set of fields of a single CDR. E.g.:

<?xml version="1.0" encoding="UTF-8"?>
<cdrs>
 <cdr> 
  <id_service_provider> FieldValue </id_service_provider> 
  <id_application> FieldValue </id_application> 
  <id_event> FieldValue </id_event> 
  <id_correlation> FieldValue </id_correlation> 
  <purchase_code> FieldValue </purchase_code> 
  <parent_app_id> FieldValue </parent_app_id> 
  <product_class> FieldValue </product_class> 
  <description> FieldValue </description> 
  <cost_currency> FieldValue </cost_currency> 
  <cost_units> FieldValue </cost_units> 
  <tax_currency> FieldValue </tax_currency> 
  <tax_units> FieldValue </tax_units> 
  <cdr_source> FieldValue </cdr_source> 
  <id_operator> FieldValue </id_operator> 
  <id_country> FieldValue </id_country> 
  <time_stamp> FieldValue </time_stamp> 
  <id_user> FieldValue </id_user>
 </cdr>
</cdrs>

or of a CDRs list:

<?xml version="1.0" encoding="UTF-8"?>
<cdrs>
 <cdr> ... </cdr>
 ...
 <cdr> ... </cdr>
</cdrs>

RS Models Management

Create RS Models

This operation allows the creation of RS Models for the given application provider.

Verb URI Description
POST /rss/rsModelsMgmt Create RS Models for a provider
Request Body

The request body of a POST operation should contain a set of fields. E.g.:

  {"appProviderId":"conwet",
   "productClass":"music",
   "percRevenueShare":50
  }

Get existing RS Models

This operation allows getting existing RS models of service providers in a Store that have been previously defined.

Verb URI Description
GET /rss/rsModelsMgmt Get the existing RS Models


Query parameters

Optional parameters that could be sent, to filter the information received (If not parameters are sent, every RS model for every service provider in the Store sending the command will be shown):

  • appProviderId: unique identifier of the provider. Only RS models for this provider would be shown.
  • productClass: identifier of type of product to apply the model. Only RS models of this type for any provider (or for the provider specified in the appProviderId parameter) would be shown.

Update RS Models

This operation allows the updating of RS Models for the given application provider.

Verb URI Description
PUT /rss/rsModelsMgmt Update RS Models for a provider
Request Body

The request body of a PUT operation should contain a set of fields. E.g.:

  {"appProviderId":"conwet",
   "productClass":"music",
   "percRevenueShare":60
  }

Delete existing RS Models

This operation allows deleting RS Models previously defined.

Verb URI Description
DELETE /rss/rsModelsMgmt Delete existing RS Models
Query parameters

Optional parameters that could be sent, to filter the RS models to delete.

  • appProviderId: Mandatory parameter that represents the unique identifier of the provider. Would delete every RS model for this provider.
  • productClass: identifier of type of product to apply the model. Would delete every RS model of this type of class for the service provider specified in the appProviderId parameter. This parameter is optional.

Expenditure Limits API REST

These APIs are related to the methods detailed in https://forge.fi-ware.org/plugins/mediawiki/wiki/fiware/index.php/FIWARE.ArchitectureDescription.Apps.RSS#Expenditure_Limits

Expenditure limit management

Get existing limits of a provider

This operation allows getting the limits information of a provider.

Verb URI Description
GET /expenditureLimit/limitManagement/{providerId} Get the existing limits for a provider
Query parameters

Optional parameters that could be sent, to filter the information received:

  • type: type of limit.
  • currency: identifier of the currency.

Create or update limits of a provider

This operation allows creating or updating the general data related to the expenditure limit for any user in a given application provider.

Verb URI Description
POST /expenditureLimit/limitManagement/{providerId} Create or update limits for a provider
Request Body

The request body of a POST operation should contain a set of fields. E.g.:


{ "service": "fiware",
 "limits": [
  {"type": "perTransaction",
   "currency": "EUR", 
   "maxAmount": 100,
},
{ "type": "weekly",
  "currency": "GBP",
  "maxAmount": 500
},
{ "type":"daily",
  "currency": "EUR",
  "maxAmount": 200
},
{ "type":"monthly",
  "currency": "EUR",
  "maxAmount": 5000
},
{ "type":"monthly",
  "currency": "GBP",  
  "maxAmount": 3000
}
]
}

Delete limits of a provider

This operation allows deleting the user expenditure limit information and implies the cascade deletion of the pairs Provider-user where the application provider is providerId.

Verb URI Description
DELETE /expenditureLimit/limitManagement/{providerId} Delete existing limits of a provider
Query parameters

Optional parameters that could be sent, to filter the results over which the delete operation will be performed

  • type: type of limit.
  • currency: identifier of the currency

Get limits of a customer

This operation allows getting the expenditure limits information of a customer.

Verb URI Description
GET /expenditureLimit/limitManagement/{providerId}/{userId] Get the existing limits for a customer
Query parameters

Optional parameters that could be sent, to filter the information received:

  • type: type of limit.
  • currency: identifier of the currency

Create or update limits of a customer

This operation allows the creation or update of the expenditure limit data related to a specific user and a specific application provider.

Verb URI Description
POST /expenditureLimit/limitManagement/{providerId}/{userId} Create or update limits for a customer
Request Body

The request body of a POST operation should contain a set of fields. E.g.:


{ "service": "fiware",
 "limits": [
  {"type": "perTransaction",
   "currency": "EUR", 
   "maxAmount": 100,
},
{ "type": "weekly",
  "currency": "GBP",
  "maxAmount": 500
},
{ "type":"daily",
  "currency": "EUR",
  "maxAmount": 200
},
{ "type":"monthly",
  "currency": "EUR",
  "maxAmount": 5000
},
{ "type":"monthly",
  "currency": "GBP",  
  "maxAmount": 3000
}
]
}

Delete limits of a customer

This operation delete the expenditure limit data related to a specific user and a specific application provider.

Verb URI Description
DELETE /expenditureLimit/limitManagement/{providerId}/{userId} Delete existing limits of a customer
Query parameters

Optional parameters that could be sent, to filter the results over which the delete operation will be performed:

  • type: type of limit.
  • currency: identifier of the currency.

Balance and Accumulated management

Get user accumulated expenses

This operation allows getting the cumulative expenses of a customer.

Verb URI Description
GET /expenditureLimit/balanceAccumulated/{userId]?QueryParameters Get the current accumulated expenses of a customer
Query parameters

Optional parameters that could be sent, to filter the information received:

  • type: type of limit.

Check user balance

This operation allows checking if the customer has enough balance to purchase an application without exceeding the expenses limit.

Verb URI Description
POST /expenditureLimit/balanceAccumulated/{userId} Check the balance of a customer
Request Body

The request body of a POST operation should contain a set of fields. E.g.:


 {"service": "fiware",
  "appProvider": "conwet",
  "currency": "EUR",
  "chargeType":"C",
  "amount": 1000
 }

Update user accumulated expenses

This operation allows updating the cumulative expenses of a customer after performing a purchase.

Verb URI Description
PUT /expenditureLimit/balanceAccumulated/{userId} Update the cumulative expenses of a customer
Request Body

The request body of a PUT operation should contain a set of fields. E.g.:

{  "service": "fiware",
  "appProvider": "conwet",
  "currency": "EUR",
  "chargeType":"C",
  "amount": 1000
 }

Delete user accumulated expenses

This operation resets the cumulative expenses of a customer.

Verb URI Description
PUT /expenditureLimit/balanceAccumulated/{userId}/reset Delete the cumulative expenses of a customer
Request Body

The request body of a PUT operation should contain a set of fields. E.g.:

  { "service": "fiware",
    "appProvider": "conwet",
    "currency": "EUR",
    "type": "monthly"
  }

Status Codes

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. The response will contain an entity describing or containing the result of the action.


201 Created

The request has been fulfilled and resulted in a new resource being created


202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.


204 No Content

The server successfully processed the request, but is not returning any content.


400 Bad Request

The request cannot be fulfilled due to bad syntax.


401 Unauthorized

Specifically for use when authentication is required and has failed or has not yet been provided.


404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.


409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict.


500 Internal Server Error

A generic error message, given when no more specific message is suitable.
Personal tools
Create a book