Federation API description

Contents

Component description

Contrail package Federation-api provides RESTful API towards the Contrail federation.

Missing

Patch file for  /etc/tomcat6/server.xml :

  • definition of connectors for ports 8080 and 8443

Resources used

  • Tomcat6
  • (HTTP) port 8080
  • (HTTPS) port 8443

Certificates

Certificates for SSL reside under  /var/lib/contrail/federation-api . These certificates are only for testing purposes. For production someone has to set up PKI.

Certificates 

  •  ca.crt  is root CA certificate 
  •  ca.key  is root CA key
  •  contrail-federation-api.crt  is federation-api's certificate issued by root CA - PEM format
  •  contrail-federation-api.p12  is federation-api's certificate issued by root CA - PKCS12 format, used by tomcat's settings
  •  contrail-federation-api.key  is federation-api's key issued by root CA - PEM format
  •  contrailTrustStore  is truststore made with ca.crt and contrail-federation-web.crt, used by tomcat's settings
  •  contrail-federation-web.crt  is federation-web's certificate issued by root CA - PEM format
  •  README.txt  how root CA and certificates were made for testing purposes

Configuration Files

Configuration file resides under

/etc/contrail/federation-api/federation-api.cfg

/etc/contrail/federation-api/federation-api.cfg

#------------------------------------------------------------------------------------------
#   Federation API configurations
#------------------------------------------------------------------------------------------

# federation-core-class=FederationCoreImpl   # is the one developed by CNR
# federation-core-class=FederationCoreBasic  # Does nothing - only implements the IFederationCore
federation-core-class=FederationCoreBasic

# Authorization
authz-enabled=false
# available engines: HerasafAuthorizer, SoapXACMLAuthorizer
authz-engine=HerasafAuthorizer

# SoapXACMLAuthorizer configuration
SoapXACMLAuthorizer-pdp-url=http://localhost:8080/contrailPDPwebApplication/contrailPDPsoap

# Herasaf-Authorizer configuration
HerasafAuthorizer.defaultPolicy=/usr/local/xacml/policy.xml
HerasafAuthorizer.mongodb.host=localhost
HerasafAuthorizer.mongodb.port=27017
HerasafAuthorizer.mongodb.database=xacml-policy-repository

# Federation-id-prov
Federation-id-prov.enabled=false
Federation-id-prov.uri=http://0.0.0.0:8080/federation-id-prov/

#------------------------------------------------------------------------------------------
#   FederationCoreImpl: Federation Core configurations
#------------------------------------------------------------------------------------------
pdp_path = http://146.48.96.75:2000/contrailPDPwebApplication/contrailPDPsoap
user_db_path = /usr/local/usersdb
image_store_path = /usr/local/imagestore

/etc/tomcat6/server.xml

We need to add secure connector under  /etc/tomcat6/server.xml 

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol"
SSLEnabled="true" maxThreads="150" scheme="https" keystoreType="PKCS12"
secure="true" clientAuth="true" sslProtocol="TLS"
keystoreFile="/var/lib/contrail/federation-api/contrail-federation-api.p12"
keystorePass="contrail" truststoreType="JKS" truststoreFile="/var/lib/contrail/federation-api/contrailTrustStore"
truststorePass="contrail" ciphers="SSL_RSA_WITH_RC4_128_SHA" />

/var/lib/tomcat6/webapps/federation-api/WEB-INF/web.xml

In order to turn on SSL, we need to modify section under  web.xml 

    <security-constraint>
       <web-resource-collection>
           <web-resource-name>REST services</web-resource-name>
           <url-pattern>/*</url-pattern>
       </web-resource-collection>
       <user-data-constraint>
           <transport-guarantee>CONFIDENTIAL</transport-guarantee>
       </user-data-constraint>
   </security-constraint>

Public API - federation-api

List of federation-api resource sections:

  • providers
  • users
  • attributes

Section: Providers

Resource URL: /providers

REST call GET

Description

  Returns a list of all providers the current user has access to.    

Example request

  GET http://172.16.117.111:8080/federation-api/providers

Example result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "name": "CloudProvider2",
       "uri": "/providers/f177f79e-3e2d-4666-b74a-729cab10c661"
    },
    {
       "name": "CloudProvider",
       "uri": "/providers/34f85511-ea5d-4081-b4c7-b76406b781db"
    },
    {
       "name": "TestProvider",
       "uri": "/providers/e7fcbd5d-2864-4c57-9ed3-5ab3624a3aeb"
    },
    {
       "name": "provider-args",
       "uri": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e"
    },
    {
       "name": "XLAB-test-5",
       "uri": "/providers/9f6133a1-821c-4f29-9024-7f9057bb0b3e"
    },
    {
       "name": "xlab",
       "uri": "/providers/fbb2ee48-f128-4622-95b8-a04976074b87"
    }
]

REST call POST

Description

Creates a new provider

Parameters
name
  • required: true
  • description: Name of the provider
  • example value: providerA
Example request

 

POST --header "Content-Type: application/json" -d '{"name":"providerA"}' http://localhost:8080/federation-api/providers
Example result
HTTP/1.1 201 Created Location: http://localhost:8080/federation-api/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e

Resource URL: /providers/ID

REST call GET

Description

 Returns the provider with the specified ID
 

Example request

  GET http://172.16.117.111:8080/federation-api/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e

Example result
HTTP/1.1 200 OK
Content-Type: application/json
{
   "applications": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/applications",
   "clusters": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/clusters",
   "name": "provider-args",
   "ovfs": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/ovfs",
   "providerUri": "http://10.31.1.3:10500",
   "servers": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/servers",
   "services": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/services",
   "slats": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/slats",
   "typeId": 42,
   "uri": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e",
   "uuid": "55643c5f-6cc8-40ef-84a9-cf0218d9a76e",
   "vep-uri": "http://10.31.1.3:10500",
   "vms": "/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e/vms"
}

REST call PUT

Description

 Updates the provider with the specified ID.

Parameters

 

name
  • required: false
  • description: Name of the provider
  • example value: providerA
attributes
  • required: false
  • description: Additional attributes
  • example value: any text
providerUri
  • required: false
  • description: URI to the provider
  • example value: any URI
typeId
  • required: false
  • description: type of the provider (integer describing the provider)
  • example value: 1
Example request
  PUT --header "Content-Type: application/json" -d '{"email":"info@cloudprovider.com"}' http://172.16.117.111:8080/federation-api/providers/55643c5f-6cc8-40ef-84a9-cf0218d9a76e
Example result
HTTP/1.1 204 No Content

/providers/{provUuid}/attributes

GET

Description
Returns attributes of specified provider as JSON array. For each attribute its name, URI and value is given.

Example request
GET https://contrail.xlab.si:8443/federation-api/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes

Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "name" : "urn:contrail:names:provider:subject:num-vm-owns",
     "value" : "4",
     "uri" : "/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66"
   },
   {
     "name" : "urn:contrail:names:provider:subject:slasoi-id",
     "value" : "4730624",
     "uri" : "/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/d9e6f630-5835-11e3-949a-0800200c9a66"
   }
]

PUT

Description
Updates one or more attributes of specified provider. If a new attribute is given then it is added to the provider's attributes list otherwise the existing attribute's value is updated. The attributes must be given as JSON array, for each attribute its UUID and value. All attributes must be registered in advance by /attributes section of federation-api.

Returns:

  • 204 No Content
  • 400 Bad Request

Example request
PUT https://contrail.xlab.si:8443/federation-api/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes
Content-Type: application/json
[
   {
     'uuid' : 'ec8b9b10-5835-11e3-949a-0800200c9a66',
     'value' : '8'
   },
   {
     'uuid' : 'f5e01060-5835-11e3-949a-0800200c9a66',
     'value' : 'true'
   }
]

Example response
Status Code: 204 No Content

/providers/{provUuid}/attributes/{attrUuid}

GET

Description
Returns specified attribute as JSON object with properties name, uri and value.

Example request
GET https://contrail.xlab.si:8443/federation-api/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66

Example response
Status Code: 200 OK
Content-Type: application/json
{
  "name" : "urn:contrail:names:provider:subject:num-vm-owns",
  "value" : "8",
  "uri" : "/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66"
}

PUT

Description
Updates specified attribute's value. The request content must contain JSON object with value property.

Returns:

  • 204 No Content
  • 400 Bad Request

Example request
PUT https://contrail.xlab.si:8443/federation-api/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66
Content-Type: application/json
{
  'value' : '8'
}

Example response
Status Code: 204 No Content

DELETE

Description
Removes specified provider's attribute.

Returns:

  • 204 No Content

Example request
DELETE https://contrail.xlab.si:8443/federation-api/providers/2b82c33c-9815-4195-a1f5-d3cb91a1f921/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66

Example response
Status Code: 204 No Content

Section: Attributes

Resource URL: /attributes

REST call GET

Description

  Returns the list of all federation attributes.

Example request

List all available attributes:

curl localhost:8080/federation-api/attributes | python -mjson.tool
Example result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "name": "urn:contrail:names:provider:subject:slasoi-id",
       "uri": "/attributes/d9e6f630-5835-11e3-949a-0800200c9a66"
    },
    {
       "name": "urn:contrail:names:provider:subject:num-vm-owns",
       "uri": "/attributes/ec8b9b10-5835-11e3-949a-0800200c9a66"
    },
    {
       "name": "urn:contrail:names:federation:subject:active-vep",
       "uri": "/attributes/f5e01060-5835-11e3-949a-0800200c9a66"
    },
    {
       "name": "urn:contrail:names:provider:subject:minimum-loa",
       "uri": "/attributes/f5e11263-5835-11e3-949a-0800200c9a66"
    },
    {
       "name": "urn:contrail:names:federation:subject:current-loa",
       "uri": "/attributes/f6e21165-5835-11e3-949a-0800200c9a66"
    }
]

Resource URL: /attributes/UUID

REST call GET

Description

Get details about specific attribute.

Example request

List the LoA attribute:

root@contrail:~# curl localhost:8080/federation-api/attributes/f5e11263-5835-11e3-949a-0800200c9a66 | python -mjson.tool
Example result
HTTP/1.1 200 OK
Content-Type: application/json

{
   "defaultValue": "4",
   "description": "Minimum LoA available for specific provider.",
   "name": "urn:contrail:names:provider:subject:minimum-loa",
   "reference": "/providers",
   "uri": "http://www.w3.org/2001/XMLSchema#string",
   "uuid": "f5e11263-5835-11e3-949a-0800200c9a66"
}

Section: Users

Resource URL: /users

REST call GET

Description

  Returns the list of all federation users.

Example request
GET http://172.16.117.111:8080/federation-api/users
Example result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "uri": "/users/5a947f8c-83d3-4da0-a52c-d9436ae77bb5",
       "username": "coordinator"
    },
    {
       "uri": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936",
       "username": "admin"
    },
    {
       "uri": "/users/caa6e102-8ff0-400f-a120-23149326a936",
       "username": "contrailuser"
    },
    {
       "uri": "/users/242e8198-a724-46c1-84ec-14298fbb6920",
       "username": "rcucumber"
    }
]

REST call POST

Description

Creates new user with a UID.

Parameters
username
  • required: true
  • description: Name of the user
  • example value: contrailuser
attributes
  • required: false
  • description: additional user attributes (JSON)
  • example value: any JSON content
firstName
  • required: false
  • description: Name of the user.
  • example value: Any name
lastName
  • required: false
  • description: Last name of the user.
  • example value: Any surname
email
  • required: true
  • description: email of the user
  • example value: user@contrail.net
password
  • required: true
  • description: password of the new user
  • example value: any password
Example request

 

POST --header "Content-Type: application/json" -d '{"username":"admin", "password":"password", "firstName":"User", "lastName":"Contrail"}' http://hostname:8080/federation-api/users
Example result
HTTP/1.1 201 Created Location: http://localhost:8080/federation-api/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936

Resource URL: /users/UUID

REST call GET

Description

Returns the description of the user with the given UUID.

Example request
GET http://172.16.117.111:8080/federation-api/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936
Example result
HTTP/1.1 200 OK
Content-Type: application/json
{
   "applications": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/applications",
   "attributes": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/attributes",
   "email": "admin@contrail.eu",
   "firstName": "Administrator",
   "groups": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/groups",
   "ids": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/ids",
   "lastName": "",
   "ovfs": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/ovfs",
   "password": "$2a$06$DCq7YPn5Rq63x1Lad4c11.P4fII8YTYrgf3o7Jq9Q9i..OjKvLrFm",
   "providers": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/providers",
   "roles": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/roles",
   "slas": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/slas",
   "slats": "/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936/slats",
   "username": "admin",
   "uuid": "cb96e102-82f7-4c5f-a8f0-23149aa6a936"
}

REST call PUT

Description

Updates the user with the given id.

Parameters
attributes
  • required: false
  • description: additional user attributes (JSON)
  • example value: any JSON content
firstName
  • required: false
  • description: Name of the user.
  • example value: Any name
lastName
  • required: false
  • description: Last name of the user.
  • example value: Any surname
email
  • required: false
  • description: email of the user
  • example value: user@contrail.net
password
  • required: false
  • description: password of the new user
  • example value: any password
Example request
PUT --header "Content-Type: application/json" -d '{"password":"new_password", "firstName":"User2", "lastName":"Contrail2"}' http://hostname:8080/federation-api/users/cb96e102-82f7-4c5f-a8f0-23149aa6a936
Example result
HTTP/1.1 204 No Content

Resource URL: /users/UUID/applications

The application lifecycle is explained here. 

First, we need to register the application with the federation. This is preparation before submiting the application to cloud provider. We can use  POST  command on  /users/UUID/applications  with body defining the application (we need  slaId  referencing OVF, and  providerId ). Refer to POST subsection. 

After the application is registered, we need to submit the application to federation (some provider will be chosen base on given SLA and OVF). For this purpose, we can trigger PUT command  /users/UUID/applications/APPUUID/submit . 

Application lifecycle is handleled by commands # /users/UUID/applications/APPUUID/start  and # /users/UUID/applications/APPUUID/stop .

REST call GET

Description

Returns the description of the user's applications with the given UUID.

Example request
GET http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications
Example result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "name": "My Application",
       "uri": "/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e"
    }
]

REST call POST

Description

Registeres a new applications for a user with given UUID and applicaiton's description with the federation. This is preparation before submiting the application to the federation. 

Example 1 request
POST --header "Content-Type: application/json" -d '{"name":"My Application", "slaId":<uri_to_SLA>, "providerId":<provider_uuid> }' http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/
Example 1 result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "name": "My Application",
       "uri": "/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e"
    }
]
Example 2 request

Create an application with attribute /attributes/f5e11263-5835-11e3-949a-0800200c9a66. The attribute refers to attribute urn:contrail:names:provider:subject:minimum-loa registered with federation's resource attribute.

For additional details about attributes, refere to Attributes paragraph.

curl -X POST --header "Content-Type: application/json" -d \
 '{"name":"TestApp", "attributes": { "userSLATemplateUrl" : "localhost:8080/slat.xml", "/attributes/f5e11263-5835-11e3-949a-0800200c9a66":"3" } }' \
 localhost:8080/federation-api/users/b55c0254-a4af-4efd-8f05-259b993b2363/applications
Example 2 result
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
       "name": "My Application",
       "uri": "/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e"
    }
]

Resource URL: /users/UUID/applications/APPUUID

REST call GET

Description

Returns the description of the user's applications with the given   UUID  and application's  APPUUID .

Example request
GET http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e
Example result
HTTP/1.1 200 OK
Content-Type: application/json
{
   "applicationId": 1,
   "applicationOvf": null,
   "attributes": null,
   "deploymentDesc": null,
   "name": "My Application",
   "ovfs": [],
   "providers": [],
   "state": null,
   "uuid": "6ad216a6-0679-4f2f-9340-b00d12fe051e",
   "vms": []
}

REST call PUT

Description

Changes the application's attributes. Possible attribute that can be changed are:

  • applicationOvf
  • attributes
  • deploymentDesc
  • name
  • state
Example request

Update Application's attributes (update the attribute minimum-LoA):

curl -v -X PUT --header "Content-Type: application/json" \
 -d '{"attributes": "{\"/attributes/f5e11263-5835-11e3-949a-0800200c9a66\":\"2\",\"userSLATemplateUrl\":\"localhost\"}"  }' \
 localhost:8080/federation-api/users/b55c0254-a4af-4efd-8f05-259b993b2363/applications/55df7327-d563-4afb-b3f6-ddc966c6b948
Example result
HTTP/1.1 204 No Content

REST call DELETE

Description

Deletes the user's applications with the given   UUID  and application's  APPUUID .

Example request
DELETE http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e
Example result
HTTP/1.1 200 OK
Content-Type: application/json

Resource URL: /users/UUID/applications/APPUUID/submit

REST call PUT

Description

Submits the application to the federation.

Example request
PUT http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e/submit
Example result
HTTP/1.1 204 No Content

Resource URL: /users/UUID/applications/APPUUID/start

REST call PUT

Description

Starts the application on the federation.

Example request
PUT http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e/start
Example result
HTTP/1.1 204 No Content

Resource URL: /users/UUID/applications/APPUUID/stop

REST call PUT

Description

Stops the application on the federation.

Example request
PUT http://172.16.117.111:8080/federation-api/users/caa6e102-8ff0-400f-a120-23149326a936/applications/6ad216a6-0679-4f2f-9340-b00d12fe051e/stop
Example result
HTTP/1.1 204 No Content

Resource URL: /users/ID/dashboard

REST call GET

Description

Returns the dashboard of the user. Dashboard contains JSON document consisting of 

  • attributes
  • roles
  • groups
  • identities
  • applications
Example request
GET http://172.16.117.111:8080/federation-api/users/3/dashboard
Example result
HTTP/1.1 200 OK
Content-Type: application/json
{"roles":[{"name":"FederationCoordinator","uri":"/roles/2"}],"identities":[],"applications":[],"attributes":[],"groups":[{"name":"bronze","uri":"/groups/1"}]}

SLA Negotiation

Initiate Negotiation

Description

Creates a new negotiation session and returns session ID (negotiationId).

Usage
POST /users/{userId}/slats/{slatId}/negotiation/initiate

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID

POST parameters:
None

Example request
POST http://<host>/federation-api/users/1/slats/1/negotiation/initiate
Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "negotiationId" : "852d3267-1a6a-4d03-97c2-31897fc38b01"
}

Cancel Negotiation

Description

Cancels specified negotiation session. Returns true if cancellation succeeded, false otherwise.

Usage
POST /users/{userId}/slats/{slatId}/negotiation/{negotiationId}/cancel

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID

POST parameters:

  • cancellationReason: list of cancellation reasons
Example request
POST http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/cancel
Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : true
}

Negotiate

Description

Sends given SLA template to the cloud provider and triggers negotiation process. Returns one or more SLA template proposals.

Usage
POST /users/{userId}/slats/{slatId}/negotiation/{negotiationId}/proposals/{proposalId}/negotiate

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
  • proposalId: ID of SLA template proposal received previously from the cloud provider. If ID is 0 the initial SLA template will be used for negotation.

POST parameters:
None

Example request
POST http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/0/negotiate
Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "slatProposals" : [{
        "proposalUri" : "/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11",
        "content" : "<slam:SLATemplate xmlns:slam=\"http://www.slaatsoi.eu/slamodel\">...<\/slam:SLATemplate>",
        "userSLATemplateId" : 1,
        "created" : "Thu Nov 08 11:32:22 CET 2012"
     }
   ]
}

Get SLA template proposals

Description

Returns list of SLA template proposals used in the specified negotiation session.

Usage
GET /users/{userId}/slats/{slatId}/negotiation/{negotiationId}/proposals

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
Example request
GET http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals
Example response
HTTP/1.1 200 OK
Content-Type: application/json

[{
     "proposalId" : 11,
     "uri" : "/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11"
  }, {
     "proposalId" : 12,
     "uri" : "/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/12"
  }
]

Get SLA template proposal

Description

Returns specified SLA template proposal used in given negotiation session.

Usage
GET /slats/{slatId}/negotiation/{negotiationId}/proposals/{proposalId}

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
  • proposalId: ID of SLA template proposal
Example request
GET http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11
Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "content" : "<slam:SLATemplate xmlns:slam=\"http://www.slaatsoi.eu/slamodel\">...<\/slam:SLATemplate>",
  "userSLATemplateId" : 1,
  "created" : "Thu Nov 08 11:32:22 CET 2012",
  "slatAbstract" : {
     "slatUUID" : "Contrail-SLAT-All",
     "agreementTerms" : {
         ...
     }
  },
  "proposalId" : 11
}

Update SLA template

Description

Updates specified SLA template with the values given in the SLATAbstract data structure. Returns HTTP status code 204 No Content.

Usage
PUT /slats/{slatId}/negotiation/{negotiationId}/proposals/{proposalId}

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
  • proposalId: ID of SLA template proposal

SLATAbstract should be given as request body in JSON format.

Example request
PUT http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11

Request body

Example response
HTTP/1.1 204 No Content

Compare SLA templates

Description

Compares specified SLA template proposal (returned by the provider) to the initial
user SLA template (used at negotiation start). Compares agreement terms and corresponding guaranteed states and finds differences in the specified SLA template according to the initial SLA template. Returns comparison results in JSON format which contains one of 4 statuses of each guaranteed state and agreement term:

  • NOT_CHANGED
  • CHANGED
  • ADDED
  • REMOVED
Usage
GET /users/{userId}/slats/{slatId}/negotiation/{negotiationId}/proposals/{proposalId}/compare

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
  • proposalId: ID of SLA template proposal
Example request
GET http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11/compare
Example response
HTTP/1.1 200 OK
Content-Type: application/json

SLA Template Comparison Example

Create Agreement

Description

Creates an SLA agreement based on the SLA template proposal negotiated in previous steps.

Usage
POST /users/{userId}/slats/{slatId}/negotiation/{negotiationId}/proposals/{proposalId}/createAgreement

Path parameters:

  • userId: user ID
  • slatId: user SLA template ID
  • negotiationId: negotiation session ID
  • proposalId: ID of SLA template proposal negotiated in previous steps

POST parameters:
None

Example request
POST http://<host>/federation-api/users/1/slats/1/negotiation/852d3267-1a6a-4d03-97c2-31897fc38b01/proposals/11/createAgreement
Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "slaUri" : "/users/1/slas/8",
  "slaId" : 8,
  "slaContent" : "<slam:SLA xmlns:slam=\"http://www.slaatsoi.eu/slamodel\">...<\/slam:SLA>"
}

/users/{userUuid}/selection_criteria

GET

Description

Returns selection criteria for the specified user. For criteria not defined by the user global defaults are used.

Example request
GET http://localhost:8080/federation-api/users/f4d19b86-2d0a-356a-a7ec-f6198630e866/selection_criteria
Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "name" : "criterion1",
     "value" : 0.25
   },
   {
     "name" : "criterion2",
     "value" : 0.90
   }
]

PUT

Description

Updates selection criteria for the specified user. The request can contain the whole set of selection criteria or just changed ones (different from global defaults).

Example request
PUT http://localhost:8080/federation-api/users/f4d19b86-2d0a-356a-a7ec-f6198630e866/selection_criteria
Content-Type: application/json
[
   {
     "name" : "criterion2",
     "value" : 0.50
   }
]
Example response
Status Code: 204 No Content

Section: Applications

/applications/{appUuid}/selection_criteria

GET

Description

Returns selection criteria for the specified application. The value of each selection criterion is determined in the following order:

  • application specific value
  • user (owner of the specified application) specific value
  • global default value
Example request
GET http://localhost:8080/federation-api/applications/28819fe0-1608-11e3-8ffd-0800200c9a66/selection_criteria
Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "name" : "criterion1",
     "value" : 0.45
   },
   {
     "name" : "criterion2",
     "value" : 0.55
   }
]

PUT

Description

Updates selection criteria for the specified application. The request can contain the whole set of selection criteria or just changed ones (different from user/global defaults).

Example request
PUT http://localhost:8080/federation-api/applications/28819fe0-1608-11e3-8ffd-0800200c9a66/selection_criteria
Content-Type: application/json
[
   {
     "name" : "criterion2",
     "value" : 0.55
   }
]
Example response
Status Code: 204 No Content

Section: Selection Criteria

/selection_criteria

GET

Description

Returns a list of all registered selection criteria together with their default value.

Example request
GET http://localhost:8080/federation-api/selection_criteria
Example response
Status Code: 200 OK
Content-Type: application/json
[
   {
     "id" : 1,
     "name" : "criterion1",
     "defaultValue" : 0.25
   },
   {
     "id" : 2,
     "name" : "criterion2",
     "defaultValue" : 0.50
   },
   {
     "id" : 3,
     "name" : "criterion3",
     "defaultValue" : 1.0
   }
]

POST

Description

Registers a new selection criteria.

Example request
POST http://localhost:8080/federation-api/selection_criteria
Content-Type: application/json
{
  "name" : "criterion3",
  "defaultValue" : 1.0
}
Example response
Status Code: 201 Created
Location: http://localhost:8080/federation-api/selection_criteria/3

/selection_criteria/{scId}

GET

Description

Returns info about specified selection criteria.

Example request
GET http://localhost:8080/federation-api/selection_criteria/1
Example response
Status Code: 200 OK
Content-Type: application/json
{
  "id" : 1,
  "name" : "criterion1",
  "defaultValue" : 0.25
}

PUT

Description

Updates specified selection criterion. Following properties can be updated:

  • name
  • defaultValue

Returns:

  • 204 No Content: success
  • 400 Bad Request: invalid JSON data
  • 404 Not Found: specified selection criterion can not be found
Example request
PUT http://localhost:8080/federation-api/selection_criteria/1
Content-Type: application/json
{
  "defaultValue" : 0.20
}
Example response
Status Code: 204 No Content

DELETE

Description

Deletes specified selection criterion. Note that all corresponding user and application customized values are also deleted.

Returns:

  • 204 No Content: success
  • 404 Not Found: specified selection criterion can not be found
Example request
DELETE http://localhost:8080/federation-api/selection_criteria/1
Example response
Status Code: 204 No Content

Section: UsersUtils

This resource provides several helpful utils:

  • authenticate a user
  • filter users based on specific attributes
  • saml utils (post SAML Attribute Requests)

Resource URL: /usersutils/saml

REST call POST

In order to call the Federation API, the service will need to obtain OAuth token first. To do that, issue:

Description

Posts a SAML Attribute Request and gets a SAML Attribute Response from the Federation DB.

Example request
curl -X POST --header "Content-Type: application/soap+xml" \
 -d @samlquery.xml \
 https://contrail.xlab.si:8443/federation-api/usersutils/saml

The content of samlquery.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<soap11:Envelope xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/">
<soap11:Body>
<samlp:AttributeQuery
 xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
 ID="AttrQuery12345789"
 IssueInstant="2009-07-15T15:48:16.421Z"
 Version="2.0"
>
 <saml:Issuer
   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 >http://somecom.com/SomeJavaRelyingParty</saml:Issuer>
 <saml:Subject
   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 >
   <saml:NameID>caa6e102-8ff0-400f-a120-23149326a936</saml:NameID>
 </saml:Subject>
<!--
  <saml:Attribute
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    Name="reputation"
  />
-->
 <!--<saml:Attribute
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    Name="phone"
  /> -->
</samlp:AttributeQuery>
</soap11:Body>
</soap11:Envelope>

Please notice, that in the request towards the Federation API there is user's UUID used instead of the username. 

Example result
HTTP/1.1 200 OK
Content-Type: application/json
<?xml version="1.0" encoding="UTF-8" ?>

<soap11:Envelope
 xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"
>
 <soap11:Body>
   <saml2p:Response
     xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
     ID="_4ca8e6c82d276cadf8128b2a25559e5a"
     InResponseTo="AttrQuery12345789"
     IssueInstant="2014-01-13T08:19:26.479Z"
     Version="2.0"
   >
     <saml2:Issuer
       xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
     >federation-api</saml2:Issuer>
     <saml2p:Status>
       <saml2p:StatusCode
         Value="urn:oasis:names:tc:SAML:2.0:status:Success"
       />
     </saml2p:Status>
     <saml2:Assertion
       xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
       ID="_b1ee852080dff4a8f53a1ecddb9f4073"
       IssueInstant="2014-01-13T08:19:26.478Z"
       Version="2.0"
     >
       <saml2:Issuer>federation-api</saml2:Issuer>
       <saml2:Subject>
         <saml2:NameID
           Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
         >caa6e102-8ff0-400f-a120-23149326a936</saml2:NameID>
       </saml2:Subject>
       <saml2:Conditions
         NotBefore="2014-01-13T08:19:16.478Z"
         NotOnOrAfter="2014-01-13T08:49:26.478Z"
       />
       <saml2:AttributeStatement>
         <saml2:Attribute
           Name="urn:contrail:names:provider:subject:slasoi-id"
         >
           <saml2:AttributeValue>3</saml2:AttributeValue>
         </saml2:Attribute>
         <saml2:Attribute
           Name="urn:contrail:names:provider:subject:num-vm-owns"
         >
           <saml2:AttributeValue>0</saml2:AttributeValue>
         </saml2:Attribute>
         <saml2:Attribute
           Name="urn:contrail:names:federation:subject:role"
         >
           <saml2:AttributeValue>FederationUser</saml2:AttributeValue>
         </saml2:Attribute>
         <saml2:Attribute
           Name="urn:contrail:names:federation:subject:group"
         >
           <saml2:AttributeValue>bronze</saml2:AttributeValue>
         </saml2:Attribute>
       </saml2:AttributeStatement>
     </saml2:Assertion>
   </saml2p:Response>
 </soap11:Body>
</soap11:Envelope>