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.StoreREST - FIWARE Forge Wiki

FIWARE.OpenSpecification.Apps.StoreREST

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Store API

Please check the following FI-WARE Open Specification Legal Notice (implicit patents license) to understand the rights to use this open specification.

UPM strives to make 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. This GE specification should be implementable without requiring patent pledges. However, the Copyright Holder of this spec (UPM) is not responsible for identifying patents for which a license may be required for any implementation of this specification.

Store API Core

The Store API is a RESTful, resource-oriented API accessed via HTTP that uses various representations for information interchange. The Store Enabler is used to the manage of service offers and is responsible for supporting the purchasing process.

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 Store API. For the latter, this specification indicates the interface to be implemented and provided to clients. Software developers intending to build applications on top of FI-WARE Enablers will implement a client of the interface specification. Implementers of the GE will implement a service of the interface specification.

To use this information the reader should firstly have a general understanding of the Generic Enabler service Store. You should also be familiar with:

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

API Change History

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

Revision Date Changes Summary
Feb 06, 2014
  • Revised version
Jun 28, 2013
  • Revised version
Jan 16, 2013
  • Initial version

How to Read This Document

It is assumed that the reader is familiar with the REST architecture style. Within 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.
  • Variables are represented between brackets, e.g. {id} and in italic font. The reader can replace the id with an appropriate value.


For a description of some terms used along this document, see Store.

General Store API Information

Resources Summary

Authentication

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

Representation Format

The Store API supports at least JSON for delivering any kind of resources, it may also support simple text, XML and HTML output format. 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. Note that it is possible for a response to be serialized using a format different from the request.

The interfaces should support data exchange through multiple formats:

  • text/html - An human-readable HTML rendering of the results of the operation as output format.
  • application/json - A JSON representation of the input and output.
  • application/xml - A XML description of the input and output.
  • application/x-www-form-urlencoded - May be used for submitting using HTML forms.
  • multipart/form-data - Should be used for submitting HTML forms containing files.


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

The resource identification for HTTP transport is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

The Store API is relying on Web principles:

  • consistent URI structure based on REST style protocol
  • HTTP content negotiation to allow the client to choose the appropriate data format supporting XML, JSON, ...

Limits

The capacity of the system can be managed in order to prevent the abuse of the system through some limitations. These limitations will be configured by the operator and may differ from one implementation to other of the GE implementation.

Rate Limits

These limits are specified both in human readable wild-card and in regular expressions and will indicate for each HTTP verb which will be the maximum number of operations per time unit that a user can request. After each unit time the counter is initialized again.

In the event a request exceeds the thresholds established for your account, a 413 HTTP response will be returned with a Retry-After header to notify the client when they can attempt to try again.

Faults

Synchronous Faults

Error responses will be encoded using the most appropriated content-type in base to the Accept header of the request. In any case, the response will provide an human-readable message for displaying to end users.

XML Example:

<error>Offering already exists</error>

JSON Example:

{
    "error": "Offering already exists"
}
Fault ElementAssociated Error CodesExpected in All Requests?
Bad Request400YES
Forbidden403YES
Not Found404YES
Request Entity Too Large413YES
Internal Server error50XYES

API Operations

Managing Repositories

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/administration/repositories Gets a list of all registered repositories Mandatory
POST /api/administration/repositories Registers a repository Mandatory
GET /api/administration/repositories/{repository} Gets repository info Mandatory
DELETE /api/administration/repositories/{repository} Unregisters a repository Mandatory
PUT /api/administration/repositories/{repository} Updates repository info Mandatory

Getting repositories

Example request

GET /api/administration/repositories HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
        "name": "Example_repository",
        "host": "http://examplerepository.com"
   ]
}

Registering repositories

Example request

POST /api/administration/repositories HTTP/1.1
Content-type: application/json


{
    "name": "Example_repository",
    "host": "http://examplerepository.com"
}

Example response

HTTP/1.1 201 Created
Vary: Cookie

Unregistering repositories

Example request

DELETE /api/administration/repositories/example_repository HTTP/1.1
Accept: application/json

Example response

HTTP/1.1 204 No content
Vary: Cookie

Updating repositories

Example request

PUT /api/administration/repositories/example_repository HTTP/1.1
Content-type: application/json


{
    "name": "example_repository",
    "host": "http://examplerepository.com"
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Managing Marketplaces

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/administration/marketplaces Gets a list of all marketplaces on which the Store is registered Mandatory
POST /api/administration/marketplaces Registers the Store on a Marketplace Mandatory
GET /api/administration/marketplaces/{marketplace} Gets marketplace info Mandatory
DELETE /api/administration/marketplaces/{marketplace} Unregisters the Store on a Marketplace Mandatory
PUT /api/administration/marketplaces/{marketplace} Updates Marketplace info Mandatory

Getting Marketplaces

Example request

GET /api/administration/marketplaces HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
        "name": "Example_marketplace",
        "host": "http://examplemarketplace.com"
   ]
}

Registering the Store on Marketplaces

Example request

POST /api/administration/marketplaces HTTP/1.1
Content-type: application/json

{
    "name": "Example_marketplace",
    "host": "http://examplemarketplace.com"
}

Example response


HTTP/1.1 201 Created
Vary: Cookie

Unregistering the Store on Marketplaces

Example request

DELETE /api/administration/marketplaces/example_marketplace HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 204 No content
Vary: Cookie

Updating Marketplaces

Example request

PUT /api/administration/marketplaces/example_marketplace HTTP/1.1
Content-type: application/json

{
    "name": "Example_marketplace",
    "host": "http://examplemarketplace.com"
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Managing Revenue Sharing Systems

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/administration/rss Gets a list of all registered RSSs Mandatory
POST /api/administration/rss Registers a RSS Mandatory
GET /api/administration/rss/{rss} Gets RSS info Mandatory
DELETE /api/administration/rss/{rss} Unregisters a RSS Mandatory
PUT /api/administration/rss/{rss} Updates RSS info Mandatory

Getting RSSs

Example request

GET /api/administration/rss HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
        "name": "Example_rss",
        "host": "http://examplerss.com"
   ]
}

Registering RSSs

Example request

POST /api/administration/rss HTTP/1.1
Content-type: application/json


{
    "name": "Example_rss",
    "host": "http://examplerss.com"
}

Example response

HTTP/1.1 201 Created
Vary: Cookie

Unregistering RSSs

Example request

DELETE /api/administration/rss/example_rss HTTP/1.1
Accept: application/json

Example response

HTTP/1.1 204 No content
Vary: Cookie

Updating RSSs

Example request

PUT /api/administration/rss/example_rss HTTP/1.1
Content-type: application/json


{
    "name": "example_rss",
    "host": "http://examplerss.com"
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Managing Organizations

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/administration/organizations Gets a list of all registered organizations Mandatory
POST /api/administration/organizations Registers an organization Mandatory
GET /api/administration/organizations/{organization} Gets organization info Mandatory
DELETE /api/administration/organizations/{organization} Unregisters an organization Mandatory
PUT /api/administration/organizations/{organization} Updates organization info Mandatory

Getting Organizations

Example request

GET /api/administration/organizations HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
        "CoNWeT", "UPM"
        "tax_address": {
            "street": "C/ Los alamos n 17",
            "postal": "39011",
            "city": "Santander"
            "country": "Spain"
        },
        "payment_info": {
            "type": "MasterCard",
            "number": "5473836409374456",
            "expire_year": "2018",
            "expire_month": "5",
            "cvv2": "111"
        }
   ]
}

Registering Organizations

Example request

POST /api/administration/organizations HTTP/1.1
Content-type: application/json


{
    "name": "CoNWeT",
    "tax_address": {
        "street": "C/ Los alamos n 17",
         "postal": "39011",
         "city": "Santander"
         "country": "Spain"
    },
    "payment_info": {
         "type": "MasterCard",
         "number": "5473836409374456",
         "expire_year": "2018",
         "expire_month": "5",
         "cvv2": "111"
    }
}

Example response

HTTP/1.1 201 Created
Vary: Cookie

Unregistering Organizations

Example request

DELETE /api/administration/organizations/CoNWeT HTTP/1.1
Accept: application/json

Example response

HTTP/1.1 204 No content
Vary: Cookie

Updating Organizations

Example request

PUT /api/administration/organizations/CoNWeT HTTP/1.1
Content-type: application/json


{
    "name": "CoNWeT-UPM",
    "tax_address": {
        "street": "C/ Los alamos n 17",
        "postal": "39011",
        "city": "Santander"
        "country": "Spain"
    },
    "payment_info": {
        "type": "MasterCard",
        "number": "5473836409374456",
        "expire_year": "2018",
        "expire_month": "5",
        "cvv2": "111"
    }
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Managing User Profiles

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/administration/profiles Gets a list of all registered users Mandatory
POST /api/administration/profiles Registers an user Mandatory
GET /api/administration/profiles/{profile} Gets user profile info Mandatory
DELETE /api/administration/profiles/{profile} Unregisters an user Mandatory
PUT /api/administration/profiles/{profile} Updates user profile info Mandatory

Getting User Profiles

Example request

GET /api/administration/profiles HTTP/1.1
Accept: application/json

Example response


HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
       {
           "username": "app_provider",
           "first_name": "Antonio",
           "last_name": "Suarez Farola",
           "organization": "CoNWeT",
           "roles": ["provider", "customer"],
           "tax_address": {
               "street": "C/ Los alamos n 17",
               "postal": "39011",
               "city": "Santander"
               "country": "Spain"
           },
           "payment_info": {
               "type": "MasterCard",
               "number": "5473836409374456",
               "expire_year": "2018",
               "expire_month": "5",
               "cvv2": "111"
           }
       }
   ]
}

Registering User Profiles

Example request

POST /api/administration/profiles HTTP/1.1
Content-type: application/json


{
    "username": "app_provider",
    "first_name": "Antonio",
    "last_name": "Suarez Farola",
    "organization": "CoNWeT",
    "roles": ["provider", "customer"],
    "tax_address": {
        "street": "C/ Los alamos n 17",
        "postal": "39011",
        "city": "Santander"
        "country": "Spain"
    },
    "payment_info": {
        "type": "MasterCard",
        "number": "5473836409374456",
        "expire_year": "2018",
        "expire_month": "5",
        "cvv2": "111"
     }
}

Example response

HTTP/1.1 201 Created
Vary: Cookie

Unregistering User Profiles

Example request

DELETE /api/administration/profiles/app_provider HTTP/1.1
Accept: application/json

Example response

HTTP/1.1 204 No content
Vary: Cookie

Updating User Profiles

Example request

PUT /api/administration/profiles/app_provider HTTP/1.1
Content-type: application/json

{
    "username": "app_provider",
    "first_name": "Antonio",
    "last_name": "Suarez Farola",
    "organization": "CoNWeT",
    "roles": ["provider", "customer"],
    "tax_address": {
        "street": "C/ Los alamos n 17",
        "postal": "39011",
        "city": "Santander"
        "country": "Spain"
    },
    "payment_info": {
        "type": "MasterCard",
        "number": "5473836409374456",
        "expire_year": "2018",
        "expire_month": "5",
        "cvv2": "111"
     }
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Managing Offerings

Here we start with the description of the operation following the next table:

Verb URI Aditional Parameters Description Mandatory/Optional
GET /api/offering/offerings filter, start, limit, action, sort Get a list of all offerings Mandatory
POST /api/offering/offerings Creates a new offering Mandatory
GET /api/offering/offerings/{organization} filter, start, limit, action, sort Get a list of all offerings of an organization Mandatory
GET /api/offering/offerings/{organization}/{name} filter, start, limit, action, sort Get a list of all versions of an offering Mandatory
GET /api/offering/offerings/{organization}/{name}/{version} Get an offering Mandatory
DELETE /api/offering/offerings/{organization}/{name}/{version} Delete an offering Mandatory
PUT /api/offering/offerings/{organization}/{name}/{version} Updates an offering Mandatory
POST /api/offering/offerings/{organization}/{name}/{version}/publish Publish the offering Mandatory
POST /api/offering/offerings/{organization}/{name}/{version}/bind Binds the offering with resources Mandatory
POST /api/offering/offerings/{organization}/{name}/{version}/rating Rate and comment an offering Mandatory

It is possible to provide additional parameters in GET requests in order to limit and filter responses:

  • filter: Optional expresion to select offerings by their state.
  • start: First offering to be returned
  • limit: Number of offerings to be returned
  • action: Changes the behaviour of the request, i.e count offerings.
  • sort: Optional expression to select the expected order for the offerings, i.e date, popularity, name.
GET /api/offering/offerings?filter=purchased&start=1&limit=10

Getting Offerings

Example request:

GET /api/offering/offering HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie


[
    {
        "name":"SmartCityLights",
        "owner_organization": "CoNWeT",
        "owner_admin_user": "app_provider",
        "version": "1.0",
        "state": "published",
        "description_url": "http://examplerepository.com/storeCollection/SmartCityLights",
        "marketplaces": [example_marketplace],
        "applications": [{
            "name": "Example idM application",
            "description": "An example idM app for access controling",
            "url": "https://exampleapp.com/app"
        }],
        "resources": [{
             “name”: “Smart City Lights Mashup”,
             “version”: “1.0”,
             “description”: “This resource contains a mashup for Smart City Lights”,
        }],
        "rating": "5",
        "comments": [{
             "date": "2013/01/16",
             "user": "admin",
             "rating": "5",
             "comments": "Good offering"
        }],
        "tags": [smart, city],
        "image_url": "http://examplestore.com/media/image",
        "related_images": [],
        "offering_description": {parsed USDL description info},
    }
]

Creating Offerings

Example requests:

POST /api/offering/offering HTTP/1.1
Content-Type: application/json
Accept: application/json

{
   "name": "SmartCityLigths",
   "version": "1.0",
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "related_images": [],
   "applications": [{
       "name": "Example idM application",
       "description": "An example idM app for access controling",
       "url": "https://exampleapp.com/app"
   }],
   "resources": [{
       “name”: “Smart City Lights Mashup”,
       “version”: “1.0”,
       “description”: “This resource contains a mashup for Smart City Lights”,
   }],
   "repository": "testbed_repository",
   "offering_description": {
       “content_type”: “text/turtle”,
       “data”: "raw USDL document (RDF XML, N3 , Turtle)"
   }

}
POST /api/offering/offering HTTP/1.1
Content-Type: application/json
Accept: application/json
{
   "name": "example_offering",
   "version": "1.0",
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "applications": [{
       "name": "Example idM application",
       "description": "An example idM app for access controling",
       "url": "https://exampleapp.com/app"
   }],
   "resources": [{
       “name”: “Smart City Lights Mashup”,
       “version”: “1.0”,
       “description”: “This resource contains a mashup for Smart City Lights”,
   }],
   "related_images": [],
   "description_url”: “http://examplerepository/collection/SmartCity.rdf”
}

POST /api/offering/offering HTTP/1.1
Content-Type: application/json
Accept: application/json
{
   "name": "example_offering",
   "version": "1.0",
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "applications": [{
       "name": "Example idM application",
       "description": "An example idM app for access controling",
       "url": "https://exampleapp.com/app"
   }],
   "resources": [{
       “name”: “Smart City Lights Mashup”,
       “version”: “1.0”,
       “description”: “This resource contains a mashup for Smart City Lights”,
   }],
   "related_images": [],
   "offering_description”: {
       "description": "an example offering",
       "pricing": {
           "model": "single payment"
           "price": "1",
           "currency": "EUR"
       },
       "legal": {
           "title": "terms and conditions",
           "text": "terms and conditions that apply to the offering" 
       }
   }
}

Example response:

HTTP/1.1 201 Created
Vary: Cookie

Deleting Offerings

Example request

DELETE /api/offering/offerings/UPM/example/1.0 HTTP/1.1
Accept: application/json

Example response

HTTP/1.1 204 No Content
Vary: Cookie

Updating Offerings

Example requests

PUT /api/offering/offerings/UPM/example/1.0 HTTP/1.1
Content-type: application/json
Accept: application/json
{
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "related_images": [],
   "repository": "example_repository",
   "offering_description":  {
       “content_type”: “text/turtle”,
       “data”: "raw USDL document (RDF XML, N3 , Turtle)"
   }
}

PUT /api/offering/offerings/UPM/example/1.0 HTTP/1.1
Content-type: application/json
Accept: application/json
{
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "related_images": [],
   "repository": "example_repository",
   "description_url": "http://examplerepository/collection/SmartCity.rdf"
}

PUT /api/offering/offerings/UPM/example/1.0 HTTP/1.1
Content-type: application/json
Accept: application/json
{
   "image": {
       “name”: “catalogue.png”,
       “data”: <encoded_data>,
   },
   "related_images": [],
   "repository": "example_repository",
   "offering_description”: {
       "description": "an example offering",
       "pricing": {
           "model": "single payment"
           "price": "1",
           "currency": "EUR"
       },
       "legal": {
           "title": "terms and conditions",
           "text": "terms and conditions that apply to the offering" 
       }
   }
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Publishing Offerings

Example request

POST /api/offering/offerings/UPM/example/1.0/publish HTTP/1.1
Content-type: application/json
Accept: application/json

{
    marketplaces: [example_marketplace,]
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Binding Offerings

Example request

POST /api/offering/offerings/UPM/example/1.0/bind HTTP/1.1
Accept: application/json

{
    resources: [{
         "provider": "example_provider",
         "name": "example_resource",
         "version": "1.0"
    }]
}

Example response

HTTP/1.1 200 OK
Vary: Cookie

Rating Offerings

Example request

POST /api/offering/offerings/UPM/example/1.0/rating HTTP/1.1
Accept: application/json

{
    "rating": "5",
    "title": "Comment tittle",
    "comment": "Good offering"
}

Example response

HTTP/1.1 201 Created
Vary: Cookie

Managing Resources

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/offering/resource Get a list of all resources Mandatory
POST /api/offering/resource Creates a new resource Mandatory
GET /api/offering/resource/{provider} Get a list of all the resources of a provider Mandatory
GET /api/offering/resource/{provider}/{name} Get a list of all versions of a resource Mandatory
GET /api/offering/resource/{provider}/{name}/{version} Get a resource Mandatory
DELETE /api/offering/resource/{provider}/{name}/{version} Delete a resource Mandatory
PUT /api/offering/resource/{provider}/{name}/{version} Updates a resource Mandatory

Getting Resources

Example request:

GET /api/offering/resources HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie
[
    {
        “content_type”: "application/x-mashup+mashable-application-component"
        “description”: "Smart City Lights is an app"
        “name”: "Smart City Management"
        “version”: "1.0"
    }

]

Registering Resources

Providing the resource

Example requests:

GET /api/offering/resources HTTP/1.1
Content-type: multipart/form-data
Accept: application/json
{

   “name”: “Smart City Lights Mashup”,
   “version”: “1.0”,
   “description”: “This resource contains a mashup for Smart City Lights”,
   “content_type”: “application/x-mashup+mashable-application-component”

}
+ FILE

GET /api/offering/resources HTTP/1.1
Content-type: application/json
Accept: application/json
{

   “name”: “Smart City Lights Mashup”,
   “version”: “1.0”,
   “description”: “This resource contains a mashup for Smart City Lights”,
   “content_type”: “application/x-mashup+mashable-application-component”,
   “content”: {
       “name”: “SmartCityLights.wgt”,
       “data”: “encoded_data”
   }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Vary: Cookie

Providing a link

Example request

GET /api/offering/resources HTTP/1.1
Content-type: application/json
Accept: application/json
{
    “name”: “Smart City Lights Mashup”,
    “version”: “1.0”,
    “description”: “This resource contains a mashup for Smart City Lights”,
    “content_type”: “application//x-mashup+mashable-application-component”,
    “link”: “https://downloadmashuplink.com/smartcity”
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Vary: Cookie

Deleting Resources

Example request:

DELETE /api/offering/resources/admin/example_resource/1.0 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content
Vary: Cookie

Updating Resources

Example request:

PUT /api/offering/resources/admin/example_resource/1.0 HTTP/1.1
Accept: application/json

{

    “name”: “Smart City Lights Mashup”,
    “version”: “1.0”,
    “description”: “This resource contains a mashup for Smart City Lights”,
    “content_type”: “application//x-mashup+mashable-application-component”,
    “link”: “https://downloadmashuplink.com/smartcity”
}

Example response:

HTTP/1.1 200 OK
Vary: Cookie

Managing purchases

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
POST /api/contracting Creates a new purchase (Buy an offering) Mandatory
GET /api/contracting/{reference} Get a purchase info Mandatory
POST /api/contracting/{reference}/accounting Provide accounting info for pay-per-use offerings Mandatory
POST /api/contracting/form Get an endpoint for purchase an offering using the web GUI Mandatory

Purchasing an Offering

Example request:

POST /api/contracting HTTP/1.1
Content-type: application/json
Accept: application/json
{
   “offering”: {
       “organization”: "CoNWeT"
       “name”: "SmartCityLights"
       “version”: "1.0"
   },
   “tax_address”: {
       “street”: "C/Los alamos n 17",
       “city”: "Santander",
       “postal”: "39011",
       “country”: "Spain"
   }
   “payment_info”: {
       “payment_method”: “credit card”,
       “credit_card”: {
           “number”: "546798367265",
           “type”: "MasterCard",
           “expire_year”: "2018",
           “expire_month”: "5",
           “cvv2”: "111"
       }
   }
}


Example response:

HTTP/1.1 201 Created
Vary: Cookie

Example request

POST /api/contracting HTTP/1.1
Content-type: application/json
Accept: application/json
{ 
    “offering”: {
        “organization”: "CoNWeT"
        “name”: "SmartCityLights"
        “version”: "1.0"
    },
    “tax_address”: {
        “street”: "C/Los alamos n 17",
        “city”: "Santander",
        “postal”: "39011",
        “country”: "Spain"
    }
    “payment_info”: {
        “payment_method”: “paypal”
    }
}


Example response

HTTP/1.1 201 Created
Vary: Cookie
{
    "redirection_link": "http://paypalredirectionlink.com/"
}


Getting a Purchase info

Example request

GET /api/contracting/12345678 HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 201 Created
Vary: Cookie


{
   {
       "reference": "12345678",
       "offering": {
            "organization": "UPM",
            "name": "example_offering",
            "version": "1.0"
        },
        "user": "admin",
        "tax_address": "Example street",
        "bill": "http://examplestore.com/bills/12345678",
    }
}

Providing Accounting info

Example request

POST /api/contracting/12345678/accounting HTTP/1.1
Content-type: application/json
Accept: application/json
{
    “offering”: {
        “name”: “offering_name”
        “version”: “1.0”
        “organization”: “organization”
    },
    “customer”: “test_user”,
    “correlation_number”: “1”,
    “time_stamp”: “2013-07-01T10:00:00-0”
    “record_type”: “event”,
    “value”: “1”,
    “unit”: “issue”
}

Example response

HTTP/1.1 200 OK
Vary: Cookie


Getting a Purchase Endpoint

Example request

POST /api/contracting/form HTTP/1.1
Accept: application/json
{
    "offering": {
        "organization": "CoNWeT",
        "name": "SmartCityLights",
        "version": 1.0,
    },
    "redirect_uri": "http://customerredirecturi.com"
}

Example response:

HTTP/1.1 201 Created
Vary: Cookie
{
    "url": "http://wstore.lab.fi-ware.eu/contracting/form?ID=63865adf6c2ca6f7"
}

Managing searches

Here we start with the description of the operation following the next table:

Verb URI Description Mandatory/Optional
GET /api/search/{keyword} Gets a list of offerings depending on keyword value Mandatory

Searching offerings

Example request:

GET /api/search/example HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Vary: Cookie

{
   [
      {
          "name":"example_offering",
          "owner_organization": "UPM",
          "owner_admin_user": "admin",
          "version": "1.0",
          "state": "published",
          "description_url": "http://examplerepository.com/example_offering",
          "marketplaces": [example_marketplace],
          "resources": [],
          "applications": [{
              "name": "Example idM application",
              "description": "An example idM app for access controling",
              "url": "https://exampleapp.com/app"
          }],
          "rating": "5",
          "comments": [{
              "date": "2013/01/16",
              "user": "admin",
              "rating": "5",
              "comments": "Good offering"
          }],
          "tags": [example,],
          "image_url": "http://examplestore.com/media/image",
          "related_images": [],
          "offering_description": {parsed USDL description info},      }
   ]
}

Status Codes

200 OK

The request was handled successfully and transmitted in response message.

201 Created

The request was fulfilled and resulted in a new resource being created.

204 No Content

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

304 Not Modified

Indicates the resource has not been modified since last requested. Typically, the HTTP client provides a header like the If-Modified-Since header to provide a time against which to compare. Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.

400 Bad Request

The request could not be fulfilled due to bad syntax.

403 Forbidden

The request could not be fulfilled due to an authorization problem.

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.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.

502 Bad gateway

An error message showing an error in a request made by the server.
Personal tools
Create a book