==============================================
The *-PaaS API specification version 1.5
==============================================
Authors: Mohamed Moahemd, Mohamed Sellami, Sami Yangui, Samir Tata --> implement the COAPS API
         Eman Hossny, Sherif Khattab, Fatma Omara, Hisham Hassan --> extended the COAPS API to include GAE platform.

Contributor: Telecom SudParis

****************
A. Description
****************

*-PaaS API
-------------------------------------------------------------------------
*-PaaS API is a generic REST API, that allows a platform to seamlessly interact with different and heterogeneous PaaS providers.

It exposes several interfaces that has be implemented according to the different actions that can exposes a PaaS provider to manage applications and environments. 

*********
B. Build
*********

Requirements: Maven Maven 3.0.4

1. Create a clone of the  folder
2. In the root directory run mvn install

This action will package the different sub-modules:

- api: the jar file of the *-PaaS API
- core: three war files associated to the cloudFoundry, the Openshift, and Google App Engine implementations of API
- client: a war file containing a Web client

*****************
C. Folder content
*****************

1. spec
-------
This folder contains the *-PaaS API specification (V1.5).

2. manifests
-------------
This folder contains manifest models used by our implementations to describe:

- Environnement,
- Application,

3. api
-------
This folder contains the java interfaces of *-PaaS API. The current version ensures application and environment management operations.

4. core
--------

This folder contains two subfolders: 

- [CloudFoundry-api] : the CloudFoundry implementation of the *-PaaS API.
- [OpenShift-api] : the OpenShift implementation of the *-PaaS API.
- [Google App Engine-api] : the Google App Engine implementation of the *-PaaS API.

After the maven build (section B), a Web application (i.e. war file) is generated in each sub-folder. These applications have to be deployed on a Web server and will acts a REST server which allows interacting with a CloudFoundry/an Open Shift PaaS instance.
 
To invoke API actions, one can use our Web-based client (see Section 5) or any REST client (eg. CURL).

Requirements: 
	* Web container: Apache Tomcat (V7)
	* Runtime: Java 1.6

Usage:

1. Deploy the generated WAR file (CF-api.war for the CloudFoundry implementation respectively OS-api.war for the openshift implementation) on tomcat,
2. Type http://localhost:8080/CF-api/ (respectively http://localhost:8080/OS-api/) in your browser to test. You should get a message indicating that your CloudFoundry (respectively Openshift) implementation is correctly running.
3. Configure your CloudFoundry (respectively Openshift) account by updating the parameters in credentials.properties. (WEB-INF/classes/telecom/sudparis/eu/copaas/core/server/ressources/credentials.properties).
4. Invoke an action (e.g create application):

- **using CURL**: curl -X POST -d @{URL-of-XML-CloudAppDescriptor} -H "Content-Type: application/xml" http://{hostname}:{port}/CF-api/rest/app
- **using our Web-based client**: see Section 5.

5. client
----------
This folder contains a Web-based client to execute the different implementations. Use maven (see section B) to build the client and deploy it on tomcat. To run the client, type (http://localhost:8080/client/) in your browser. Then, you can select the PaaS instance to interact with (only CloudFoundry and Openshift are available) before following one of the test scenarios detailed below.

5.1 CloudFoundry test scenario
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To deploy an application on a running CloudFoundry instance, one should follow these steps:

- Access the client interface at http://localhost:8080/client/
- Select the CloudFoundry PaaS solution.
- Create an environment: select the "create environment" action from the action list and provide the manifest fragment describing the needed environment for the application to deploy (runtimes, frameworks, etc.). In the body of the request just paste the content of test-resources/CloudFoundry-test-manifests/EnvironmentManifest.xml (without the license comment). If additional nodes are needed, a database for example, the Environment manifest must be updated accordingly. To add a mysql database in the environment for example, add this element <paas_node content_type="database" name="mysql" version="2.2" provider="CF"/> after the existing <paas_node> element. After submitting this requested (i.e. the submit button), an XML description of the created environment is returned. From this descriptor, you have to ''save'' the returned "envid" that must be provided later to link this environment to the application to deploy (deployApplication action).
- Create the application: select the "create application" action from the action list and provide the manifest describing the application. In the body of the request just paste the content of test-resources/CloudFoundry-test-manifests/ApplicationManifest.xml (without the license comment). In the same way as the created environment, an "appid" will be provided by the API.
 **IMPORTANT**: Here do not forget to modify the ApplicationVersionManifest to change the name of the application (if needed) and to specify the path of the application to deploy in the <paas_deployable> element.
- Deploy the application (from the ApplicationManager Operations): select the "deploy application" action from the action list while specifying the environment identifier "envid" and the application identifier "appid" in the path.
- Start the application: select the "start application" action from the action list and provide the application	identifier "appid" in the path. In the returned application description, you can find the url of the deployed application.
- The application is now accessible via a browser on the returned URL.

5.2 Openshift test scenario
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To deploy an application on a running CloudFoundry instance, one should follow these steps:	

- Access the client interface at http://localhost:8080/client/
- Select the Openshift PaaS solution.
- Create an environment: select the "create environment" action from the action list and provide the manifest fragment describing the needed environment to deploy the application (runtimes, frameworks, etc.). The returned "envname" must be provided later to map between this environment and the application to deploy (deployApplication action).
- Create the application: select the "create application" action from the action list and provide the manifest fragment describing the application (application name, artifacts, instances number, environment name "envname", etc.). **IMPORTANT**: Here do not forget to specify the name and the path of the application to deploy.
- Deploy the application: select the "deploy application" action from the action list while specifying the environment name "envname" and the application identifier "appid". An application "URL" and a "GitURL" will be returned by the API.
- The application is accessible via a browser on the returned URL. To update the application, one should update its Git accessible on the returned "GitURL".

5.1 Google App Engine test scenario
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To deploy an application on Google App Engine platform, one should follow these steps:

- Access the client interface at http://localhost:8080/client/
- Select the GoogleAppEngine PaaS solution.
- Create an environment: select the "create environment" action from the action list and provide the manifest fragment describing the needed environment for the application to deploy (runtimes, frameworks, etc.). In the body of the request just paste the content of test-resources/CloudFoundry-test-manifests/EnvironmentManifest.xml (without the license comment). If additional nodes are needed, a database for example, the Environment manifest must be updated accordingly. To add a mysql database in the environment for example, add this element <paas_node content_type="database" name="mysql" version="2.2" provider="CF"/> after the existing <paas_node> element. After submitting this requested (i.e. the submit button), an XML description of the created environment is returned. From this descriptor, you have to ''save'' the returned "envid" that must be provided later to link this environment to the application to deploy (deployApplication action).
- Create the application: select the "create application" action from the action list and provide the manifest describing the application. 
 **IMPORTANT**: Here do not forget to modify the ApplicationVersionManifest to change the name of the application (if needed) and to specify the path of the application to deploy in the <paas_deployable> element.
- Deploy the application (from the ApplicationManager Operations): select the "deploy application" action from the action list while specifying the environment identifier "envid" and the application identifier "appid" in the path.
- Once the application is deployed, it is ready to be accessed via a browser on the returned URL.

6. test-resources
-----------------

This folder contains test materials: the manifests and a Web application that can be deployed on CF or OS.

6.1 sampleApplication
^^^^^^^^^^^^^^^^^^^^^

This subfolder contains a test servlet application to deploy.
	
6.2 CloudFoundry-test-manifests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A set of manifests describing the applications to deploy on CloudFoundry and its environments.

6.3 OpenShift-test-manifests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A set of manifests describing the applications to deploy on OpenShift and its environments.