Service Integration API Specification 1.0

Contents

Overview
- Integration Sequence
Getting Started
Authentication
API Testing
API Reference
Example API implementation
FAQ

Overview

The Service Integration API Spec provides an interface for the partner to develop in order for Pilvi to automatically integrate into the partner’s cloud service.

The partner API needs to be RESTful, served over HTTPS and use JSON messages.

Integration Sequence

The following sequence shows how a simple provisioning is performed with the Pilvi Automatic Integration Technology API (PAITA).

paita_service_integration_sequence

Getting Started

Implement Service Integration API

See API Reference and Authentication

Setup Integration

In Pilvi Manager, navigate through Settings -> Provisioning. Proceed to API page by selecting your API from the Pilvi Automatic Service Integration APIs (PAITA) list.

Insert your Api key into its place.

Connect Products to use your API as their provisioning method.

Provide URLs to your API implementation for the mandatory API methods.

Provide URLs to your API implementation for the optional API methods if implemented.

Perform first test for the getServiceParameters method. When getServiceParameters status is OK. Click the “Refresh” button before continuing with rest of the tests.

When all the mandatory methods have OK status, you can sync/refresh the parameters to your previously specified Products by clicking the “Refresh” button on the Methods section.

Setup your Products

In Pilvi Manager, navigate through Catalog -> Products. Proceed to Product page by selecting your Product from the list.

Open the Properties tab at the bottom of the page. In the Properties listing you should see the Parameters you have defined in your PAITA implementation.

In here, you can change the type of these Properties. You can make a Property optional or mandatory during the purchase process, or define static value for the current Product.

By default, all the Parameters provided through the PAITA integration are shown during the purchase process and except values from the Customer.

Authentication

Each request to the API has to be authenticated.

The partner should provide Pilvi/the merchant with an alphanumeric API key. The key needs to be between 32 and 64 characters in length. The key should be treated in case-sensitive manner.

The API key will be passed in every requests as a header parameter “x-api-key”.
API requests should be allowed only over HTTPS to ensure secure communication.

If the authentication fails, the API should respond with HTTP 401.

API Testing

You can test your API implementation from the Pilvi Manager interface.

API Reference

Swagger UI

Example API implementation

You can generate a server stub from Pilvi’s service-integration-api.json file to test the integration for your platform. You can copy the content of the json file and save it as service-integration-api.json from here:

http://developer.pilvi.com/pilvi-swagger/paita-service-integration-api.json

You also need swagger-codegen to build the server stub:

https://github.com/swagger-api/swagger-codegen

The list of technologies supported by swagger-and how to generate stubs can be found here:

https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO

For this example I have created stub using PHP Silex, which generated an index.php file. I have simplified the file and it looks like this:

<!--?php
require_once __DIR__ . '/vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Silex\Application;


$app = new Silex\Application();


/**
 * POST createService
 * Summary: Provision Service
 * Notes: This method creates a new service. 
 * Output-Formats: [application/json]
 */
$app--->POST('/yourapp/v1/services', function(Application $app, Request $request) {
            $dummy = $request-&gt;get('dummy');
            return new Response('How about implementing createService as a POST method ?');
            });

/**
 * DELETE deleteServiceById
 * Summary: This method terminates an existing service.
 * Notes: This method terminates an existing service. After termination the service is considered closed. Closed services can be reactivated with the reinstate API command. 
 * Output-Formats: [application/json]
 */
$app-&gt;DELETE('/yourapp/v1/services/{serviceId}', function(Application $app, Request $request, $serviceId) {
            $dummy = $request-&gt;get('dummy');
            return new Response('How about implementing deleteServiceById as a DELETE method ?');
            });


/**
 * GET getServiceParameters
 * Summary: Specify Service Provisioning Parameters
 * Notes: This method specifies the parameters the partner needs in order to provision a service. 
 * Output-Formats: [application/json]
 */
$app-&gt;GET('/yourapp/v1/parameters', function(Application $app, Request $request) {
            $dummy = $request-&gt;get('dummy');
            return new Response('How about implementing getServiceParameters as a GET method ?');
            });

$app-&gt;run();

You can start the server for example at localhost port 8080 and run your index file from there:

sudo php -S localhost:8080 -t example example/index.php

Now you can run your index file at your browser and return GET response by typing:

http://localhost:8080/yourapp/v1/parameters

FAQ

How to define Product Plans?

Option 1: Plans are defined on Pilvi’s end
Partner defines parameters which form the Plan.
Different combinations of these parameter values form the Plans.
Values can be defined per product from the Pilvi Manager interface.

Example:

Parameter 1: 'user.count'
Parameter 2: 'bandwidth.limit'

Product Name: 'Trial Product'
Product property 'user.count' with value '1'		
Product property 'bandwidth.limit' with value '10000'

Product Name: 'Premium Product'
Product property 'user.count' with value '5'		
Product property 'bandwidth.limit' with value '60000'

Option 2: Plans are defined on Partner’s end
Partner defines a parameter which identifies the Plan.
This parameter value tells the Partner which Plan to provision.
Values can be defined per product from the Pilvi Manager interface. You can also define all available plans as parameter options.

Example:

Parameter: 'plan'

Product Name: 'Trial Product'
Product property 'plan' with value 'trial'

How are parameters shown in the UI?

Pilvi has five different types of property values. Parameters you define in your /parameters response are mapped to these types in the following way.

Property Value type	UI element	Conditions
String	input[type=’text’]	Parameter is of type ‘string’
Number	input[type=’number’]	Parameter is of type ‘number’
Range	input[type=’range’]	Parameter is of type ‘number’ Parameter has limits defined
Boolean	input[type=’checkbox’]	Parameter is of type ‘bool’
Option	select	Parameter is of type ‘string’ Parameter has options defined

How do different types of parameters behave?

Regular parameter types (string, number, bool) are shown in the Product configuration phase as described in How are parameters shown in the UI?

Type name	Value type
string	String
number	Integer
bool	Boolean

Special parameter types are not shown in the Product configuration phase. Values for these parameters are gathered by the Pilvi platform during the checkout process.

Type name	Value type	Description
userid	Integer	Unique identifier for the User that made the order
email	String	Email Address of the User
firstname	String	Firstname of the User
lastname	String	Lastname of the User
customerid	Integer	Unique identifier for the Customer that the User made the order for
sellerid	Integer	Unique identifier for the Seller that the Product is bought from

How to structure the Service orchestration layer?

There many ways to implement the Service orchestration layer on partner’s end. Here are two high level architectural suggestions to consider before starting your implementation.

Option 1: Your Services/Subscriptions are provided from a Shared or Single environment

Implement PAITA API directly into your code base. Handle orchestration inside your application, eg. create necessary accounts etc directly from the API implementation.

Create PAITA implementation in the same language that your application is coded in. Use generated code stubs to kick-start development if available for your language.

Option 2: Your Services/Subscriptions are provided from a Separate or Hybrid environments

Have a single endpoint for managing Service/Subscription life times. Implement PAITA API on this endpoint and perform orchestration from this endpoint.

Create PAITA implementation in the language of your choosing that communicates fluently with the orchestration implementation you are using. Use generated code stubs to kick-start development if available for your language.