[Fiware-cloud] Fw: Review of Cloud Chapter: API Specifications and Apiary Projects

[Kenneth Nagin]

Please see Phillip's review and make changes where necessary.


----- Forwarded by Kenneth Nagin/Haifa/IBM on 04/09/2016 11:28 AM -----

From:   MIGUEL CARRILLO PACHECO <miguel.carrillopacheco at telefonica.com>
To:     Kenneth Nagin/Haifa/IBM at IBMIL
Date:   02/09/2016 02:26 PM
Subject:        Fwd: Review of Cloud Chapter: API Specifications and 
Apiary Projects



hi Kenneth,
Please distribute
Regards,
Miguel


-------- Mensaje reenviado -------- 
Asunto: 
Review of Cloud Chapter: API Specifications and Apiary Projects
Fecha: 
Mon, 29 Aug 2016 09:48:52 +0200
De: 
Torsten Spieldenner <torsten.spieldenner at dfki.de>
Para: 
MIGUEL CARRILLO PACHECO <miguel.carrillopacheco at telefonica.com>
CC: 
Philipp Slusallek <philipp.slusallek at dfki.de>


Good morning,
please find my review for the Cloud Chapter API Specifications below. 
Overall, the existing documentation was detailed and easy to follow, with 
only two exceptions: Cloud Service Interface that does not provide any API 
specification, and Cloud Object Storage that does provide a rather short 
documentation that is moreover hosted directly on GitHub. One general 
thing that I noticed across the whole chapter was that the specifications 
are often hosted on different platforms than the ones requested in FIWARE, 
or don't seem to be created using Apiary. Docker and IaaS are hosted in 
their own locations, using an individual style and layout each.
Following comments on each of the GE API specifications:
Docker:
Thorough documentation of the API. Diagram that shows the container states 
that can be accessed and changed via the API is detailed and helpful. 
The specification is embedded into the public Docker documentation and is 
not provided as Apiary documentation. In the summary sheet, the links to 
the  Apiary project and actual specification point to the same resource.
IaaS:
The link given in the Open Specs document is pointing to a collection of 
Open Stack API specifications for various versions. It also lists 
documentation for deprecated and experimental versions which is very 
helpful for users that are working on these states of the software. Each 
of the specification clearly describes the URLs, HTTP Methods, parameters, 
and results for every possible request. 
One confusing thing is that being taken to the documentation from the GE 
called "IaaS", the user is taken to a website that seems to use a 
different nomenclature. The APIs listed in the menu are for example called 
Bare Metal, Block Storage, Clustering, Identy, and others, and also in the 
introduction section, there is no direct connection established to what 
exactly is encompassed in the IaaS Generic Enabler. 
The documentation is embedded into the OpenStack documentation and does 
not provide an Apiary source. In the summary sheet, the links to the 
Apiary project and actual specification point to the same resource. 
Cloud Object Storage:
The link given in the summary page points directly to the GitHub sources, 
and not to a compiled website that is hosted on GitHub pages. 
The documentation seems brief, yet exhaustive. It deals with retrieving 
existing storlets, updating existing ones, and creating new storlets. 
Links to other sources of documentation (e.g. "Storlet writing and 
deploying guide") also point directly to the GitHub resources, instead of 
a compiled page 
One link reference in the documentation is broken: 
https://github.com/openstack/storlets/blob/master/doc/source/invoking_storlets.rst 

Cloud Service Interface:
Does not provide an API specification 
Cloud Application Management (Murano):
Very thorough documentation that clarifies HTTP response codes, headers, 
and used terms directly at the beginning 
Each request is explained with a throrough example for parameters and 
responses 
The Specification is hosted on ReadTheDocs and does not provide an Apiary 
source 
Policy Manager
API Specification: Points to a documentation on ReadTheDocs. It lists 
detailed examples for requests and responses, and explains well how to use 
the documented API.
Apiary Project: Points to a detailed Apiary created specification that 
explains all listed operations in detail. 

Best Regards,
Torsten
-- 
Torsten Spieldenner, M.Sc.

Tel.: +49 6 81 / 8 57 75 - 77 48
Fax.: +49 6 81 / 8 57 75 - 22 35

Internet: http://www.dfki.de/web/forschung/asr/

-------------------------------------------------------------
Deutsches Forschungszentrum fuer Kuenstliche Intelligenz GmbH
Trippstadter Strasse 122, D-67663 Kaiserslautern, Germany

Geschaeftsfuehrung:
Prof. Dr. Dr. h.c. mult. Wolfgang Wahlster (Vorsitzender)
Dr. Walter Olthoff

Vorsitzender des Aufsichtsrats:
Prof. Dr. h.c. Hans A. Aukes

Amtsgericht Kaiserslautern, HRB 2313
------------------------------------------------------------- 


Este mensaje y sus adjuntos se dirigen exclusivamente a su destinatario, 
puede contener información privilegiada o confidencial y es para uso 
exclusivo de la persona o entidad de destino. Si no es usted. el 
destinatario indicado, queda notificado de que la lectura, utilización, 
divulgación y/o copia sin autorización puede estar prohibida en virtud de 
la legislación vigente. Si ha recibido este mensaje por error, le rogamos 
que nos lo comunique inmediatamente por esta misma vía y proceda a su 
destrucción.

The information contained in this transmission is privileged and 
confidential information intended only for the use of the individual or 
entity named above. If the reader of this message is not the intended 
recipient, you are hereby notified that any dissemination, distribution or 
copying of this communication is strictly prohibited. If you have received 
this transmission in error, do not read it. Please immediately reply to 
the sender that you have received this communication in error and then 
delete it.

Esta mensagem e seus anexos se dirigem exclusivamente ao seu destinatário, 
pode conter informação privilegiada ou confidencial e é para uso exclusivo 
da pessoa ou entidade de destino. Se não é vossa senhoria o destinatário 
indicado, fica notificado de que a leitura, utilização, divulgação e/ou 
cópia sem autorização pode estar proibida em virtude da legislação 
vigente. Se recebeu esta mensagem por erro, rogamos-lhe que nos o 
comunique imediatamente por esta mesma via e proceda a sua destruição

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-cloud/attachments/20160904/6acfc6ce/attachment.html>