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.Security.DataHandlingGE.Open RESTful API Specification - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.DataHandlingGE.Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Data Handling GE API

Please check the following FI-WARE Open Specification Legal Notice (essential patents license) to understand the rights to use this open specification. As all other FI-WARE members, SAP has chosen one of the two FI-WARE license schemes for open specifications.

To illustrate this open specification license from our SAP perspective:

  • SAP provides the specifications of this Generic Enabler available under IPR rules that allow for a exploitation and sustainable usage both in Open Source as well as proprietary, closed source products to maximize adoption.
  • This Open Specification is exploitable for proprietary 3rd party products and is exploitable for open source 3rd party products, including open source licenses that require patent pledges.
  • If the owner (SAP) of this GE spec holds a patent that is essential to create a conforming implementation of the GE spec (i.e. it is impossible to write a conforming implementation without violating the patent) then a license to that patent is deemed granted to the implementation.

Data Handling GE API Core

  1. storePii(name, value, spAttribute, owner) is a RESTful method accessed via HTTP that uses XML-based information to create a new attribute in the Database. The method takes two parameters; one for the attribute name, and the second for the attribute value. For example inserting an e-mail address with the value of test@example.com. The same method can be used with a third parameter in order to attach a sticky policy to the new attribute.
  2. updatePii(pii, name, value, spAttribute) is a RESTful method used to update an existing attribute entry in the Database. The method takes three parameters; one for the attribute name, and the second for the new attribute value, and eventually the new Sticky Policy related to this new PII.
  3. deletePii(pii) is a RESTful method used to delete an attribute from the DB. The method takes one parameter that is the attribute name.
  4. GetAllPII() is a RESTful method used to retrieve all the attributes stored in the DB.
  5. GetPII(pii) is a RESTful method used to request an attribute from the DB. The method takes one parameter that is the attribute name.

Data Handling GE API Identity Based Encryption feature

  1. CertificateRequest (commonName, Alias, Organization, OrganizationUnitName) is a RESTful method accessed via HTTP that requests the Public Key Generator (PKG) to generate a certificate containing all the information provided in the parameter plus a private key related to the Identity Alias.
  2. Keypair (Alias, keyType) is a RESTful method accessed via HTTP that requests the Public Key Generator (PKG) to generate a public and private key related to the Alias provided as argument. the parameter keytype corresponds to these three values {publickey, privatekey, keypair}
  3. cipher(inputstream, fileName, alias, mode)is a RESTful method accessed via HTTP that encrypts or decrypts (according to the parameter mode) a stream (parameter inputstream) or a file (parameter fileName).

Intended Audience

This specification is intended for Service Consumers (with development skills), Cloud Providers and reimplementers of this API. For Service Customers, this document provides a full specification of how to interoperate with the Data Handling Service API. For Cloud Providers and reimplementers, this specification indicates the interface to be provided to the client application developers to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Generic Enabler service Data Handling Generic Enabler . The API user should be familiar with:

  • RESTful web services
  • HTTP/1.1
  • JSON and/or XML data serialization formats.

API Change History

Current version is: Version 2.0.0, 28/04/2013

The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 27, 2012
  • Version 1 of the Data Handling GE API Guide.
Apr 28, 2013
  • Version 2 of the Data Handling GE API Guide.
Mar 5, 2014
  • Version 3 of the Data Handling GE API Guide.

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.

In the whole document it is taken the assumption that reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.

Additional Resources

More documentation related to the architecture and the usecase is available at Data Handling Generic Enabler

General Data Handling GE API Information

Resources Summary

The following figures depict graphical diagrams in which we can see the different URIs that we can use in the API.

File:DHGE_restful_diagram.jpg

File:API-IBE2.jpg

Representation Format

The Data Handling GE API supports the transmission of Strings and XML files. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format is always in plain text ("text/plain").

The application handles PPL Policies. PPL Language is an extension of the XACML (eXtensive Access Control Markup Language). In order to manipulate the different XML elements of the PPL language within the application, a set of POJOs has been implemented. These POJOs are mapped to XML representations using JAXB (Java Annotation Xml Binding, see http://jaxb.java.net/ for more information)

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.

API Operations

Retrieve the file of the Pii identified by the given uniqueId and Owner

/pii
GET
Parameter:
uniqueId, owner
Content:
Return:
multipart/mixed
Retrieve the file of the Pii identified by the given UniaueId and Owner.
Return
200
If file found
404
If file not found

Store a Pii (file) with its StickyPolicy

/pii
PUT
Parameter:
Content:
application/x-www-form-urlencoded
Return:
application/json
file
File
{"uniqueId" : uid }
stickyPolicy
a PPL StickyPolicy as XML String
owner
String
Store a Pii (file) with its StickyPolicy
Return
201
Pii successfully stored
500
Pii not stored, an error occured

Store a Pii with its StickyPolicy

/pii
PUT
Parameter:
Content:
multipart/form-data
Return:
application/json
name
string
{"uniqueId" : uid }
Value
string
stickyPolicy
a PPL StickyPolicy as XML String
owner
String
Store a Pii with its StickyPolicy
Return
201
Pii successfully stored
500
Pii not stored, an error occured

Update a Pii (File) and its StickyPolicy identified by the given UniqueId and Owner

/pii
POST
Parameter:
Content:
multipart/form-data
Return:
application/json
uniqueId
Long
{"uniqueId" : uid }
file
File
stickyPolicy
a PPL StickyPolicy as XML String
owner
String
Update a Pii (File) and its StickyPolicy identified by the given UniqueId and Owner
Return
200
Pii successfully updated
500
Pii not updated, an error occured
404
Pii not found

Update a Pii and its StickyPolicy identified by the given UniqueId and Owner

/pii
POST
Parameter:
Content:
application/x-www-form-urlencoded
Return:
application/json
uniqueId
Long
{"uniqueId" : uid }
Name
String
Value
String
stickyPolicy
a PPL StickyPolicy as XML String
owner
String
Update a Pii and its StickyPolicy identified by the given UniqueId and Owner
Return
200
Pii successfully updated
500
Pii not updated, an error occured
404
Pii not found

Delete a Pii identified by the given UniqueId and Owner

/pii/delete
POST
Parameter:
Content:
application/json
Return:
application/json
uniqueId
Long
{“deleted” : boolean}
owner
String
Delete a Pii identified by the given UniqueId and Owner
Return
200
See response body

Request files (Pii) identified by its name (resource) for the user (subject)

/downstreamusage/file
POST
Parameter:
Content:
application/json
Return:
multipart/mixed
Subject
String
List of files (can be empty)
Resource
String


Request files (Pii) identified by its name (resource) for the user (subject)
Return
200
See response body

Request Piis identified by its name (resource) for the user (subject)

/downstreamusage/pii
POST
Parameter:
Content:
application/json
Return:
application/json
Subject
String
Items: [Name, Value]
Resource
String
Request Piis identified by its name (resource) for the user (subject)
Return
200
See response body

Identity Based Encryption Feature API

Request certificate by the given informations ( commonName, Alias(email), organization, organizationalUnitName)

/certificate/request
POST
Parameter:
Content:
Multipart/form-data
Return:
Text/Plain
commonName
String
Generated certificate path
Alias
String
Organization
String
organisationalUnitName
String
Request certificate by the given informations ( commonName, Alias(email), organization, organizationalUnitName)
Return
200
If certificate successfully created
400
If parameter is missing

Decrypt or encrypt the inputStream / File for the given alias,mode € = { encrypt, decrypt }

/cipher/{mode}
POST
Parameter:
Content:
Multipart/form-data
Return:
Application/mixed
inputStream
inputStream
Decrypted or Encrypted file
fileName
String
alias
String
mode
String
Decrypt or encrypt the inputStream for the given alias, mode € = { encrypt, decrypt }
Return
200
If operation successfully executed
400
If one parameter is wrong
500
If input/output exception

Keypair create a key depending on the keyType € = {publickey, privatekey, keypair}

/keypair/{keyType}
POST
Parameter:
Content:
Multipart/form-data
Return:
Application/json
alias
String
Request key type
keyType
String
Keypair create a key depending on the keyType € = {publickey, privatekey, keypair}
Return
200
If key successfully created
406
If alias or keyType is wrong
400
If keyTpe don’t exist

Parameters returned can be used to regenerate the cipher from another application

/controller/
POST
Empty Parameter:
Return:
Multipart/form-data
q
String
l
String
px
String
py
String
pubx
String
puby
String
char
String
Parameters returned can be used to regenerate the cipher from another application
Return
200
Always success there is no treatment to handle
Personal tools
Create a book