[Fiware-wpa] Fwd: Re: Fwd: Peer review of FI-WARE Open Specifications

[Juanjo Hierro]

Hi all,

  Please find below the results of the peer-review of the Open Specifications of the Cloud Chapter carried out by members of the Data Chapter.

  Cheers,

-- Juanjo


-------------
Product Development and Innovation (PDI) - Telefonica Digital
website: www.tid.es<http://www.tid.es>
email: jhierro at tid.es<mailto:jhierro at tid.es>
twitter: twitter.com/JuanjoHierro

FI-WARE (European Future Internet Core Platform) Chief Architect

You can follow FI-WARE at:
  website:  http://www.fi-ware.eu
  facebook: http://www.facebook.com/pages/FI-WARE/251366491587242
  twitter:  http://twitter.com/FIware
  linkedIn: http://www.linkedin.com/groups/FIWARE-4239932



=== Review by Grant Croker
SM
URL<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/SM_Open_RESTful_API_Specification_%28PRELIMINARY%29>

  *   Additional Resources<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/SM_Open_RESTful_API_Specification_%28PRELIMINARY%29#Additional_Resources>
     *   Link to private wiki for the current version of the spec
     *   The following text should have the URL not "[2]":

For more information about OpenStack APIs please refer to [2]

  *   Resources Summary<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/SM_Open_RESTful_API_Specification_%28PRELIMINARY%29#Resources_Summary>
     *   To be consistent the URI should include

                //server


  *   Faults<file:///home/grant/Dropbox/notas/[[Resources%20Summary%7Chttps://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/SM_Open_RESTful_API_Specification_%28PRELIMINARY%29#Faults>
     *   Link goes to a "blank" page in the documentation and the reader is expected to look at the contents tree to expand the section. Perhaps it would be better to provide links to Synchronous Faults<http://docs.openstack.org/api/openstack-compute/2/content/Synchronous_Faults-d1e1729.html> and Asynchronous Faults<http://docs.openstack.org/api/openstack-compute/2/content/Asynchronous_Faults-d1e2009.html>.
  *   API Operations<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/SM_Open_RESTful_API_Specification_%28PRELIMINARY%29#API_Operations>
     *   Whilst the OpenStack Compute Developer Guide gives examples, perhaps it would be useful to direct link to an example for each operation?

DCRM
URL<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/DCRM_Open_RESTful_API_Specification_%28PRELIMINARY%29>

  *   Missing sections
     *   API Change History
     *   How to read this document
  *   Versioning<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/DCRM_Open_RESTful_API_Specification_%28PRELIMINARY%29#Versioning>
     *   Should be titled 'Versions'
  *   Error and Fault Codes<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/DCRM_Open_RESTful_API_Specification_%28PRELIMINARY%29#.C2.A0Error_and_Fault_Codes>
     *   Should be titled 'Faults' and without a leading space
  *   Resources Summary
     *   No mention of the extensions documented from OCCI Kind Extensions<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/DCRM_Open_RESTful_API_Specification_%28PRELIMINARY%29#OCCI_Kind_Extensions> and below.
  *   General comments
     *   When linking to PDF documents the chapter/section name should be referenced in the spec to make the relevant text easier to find (appending #Page=XX to the URL is also an option but requires Adobe Acrobat Reader as the rendering engine).
        *   E.g. See OCCI Kind Extensions<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/DCRM_Open_RESTful_API_Specification_%28PRELIMINARY%29#OCCI_Kind_Extensions>

Open Storage
URL<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Object_Storage_Open_RESTful_API_Specification_%28PRELIMINARY%29>

  *   Missing the following sections:
     *   API Change History table e.g. Big Data revision<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/BigData_Analysis_Open_RESTful_API_Specification_%28PRELIMINARY%29#API_Change_History>
     *   How to Read
     *   Additional Resources
     *   Links and References
  *   Error and Fault Codes<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Object_Storage_Open_RESTful_API_Specification_%28PRELIMINARY%29#.C2.A0Error_and_Fault_Codes> should be titled 'Faults'
  *   Versioning<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Object_Storage_Open_RESTful_API_Specification_%28PRELIMINARY%29#Versioning> should be titled 'Versions'
     *   The link in this section could point to http://cdmi.sniacloud.com/cdmi_spec/7-interface_specification/7-interface_specification.htm#TOC_7_1_HTTP_Status_Codesbc-1
  *   Leading space in the title for Authentication<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Object_Storage_Open_RESTful_API_Specification_%28PRELIMINARY%29#.C2.A0Authentication>
  *   Leading space in the title for API Operations<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Object_Storage_Open_RESTful_API_Specification_%28PRELIMINARY%29#.C2.A0API_Operations>
     *   Provide direct links to the chapters in http://cdmi.sniacloud.com/?

Cloud Edge Service Management.
URL<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29>

  *   Additional Resources<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29#Additional_Resources>
     *   A link to the private wiki when I guess it should be the public wiki
     *   Link to the vision for cloud should be using Wiki links rather than the absolute URL
  *   Links and References<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29#Links_and_References>
     *   Wrong sort of link/reference - should be URL redirection which does not apply to XML-RPC
  *   Synchronous Faults<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29#Synchronous_Faults>
     *   Fault codes don't match with the HTTP1.1 spec, e.g. 900 Internal is 500 Internal Server Error in HTTP/1.1<http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1> - I'm not sure this is an issue or not.
  *   API Operations (Methods details)<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29#Methods_details>
     *   No examples given - perhaps not explicity needed but I think it was requested in the original mails on this topic. Links and References<https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Cloud_Edge_Service_Management_API_Specification_%28PRELIMINARY%29#Links_and_References> provides a link to the spec.

=== end of review


-------- Original Message --------
Subject:        Peer review of FI-WARE Open Specifications
Date:   Mon, 13 Aug 2012 08:22:30 +0200
From:   Juanjo Hierro <jhierro at tid.es><mailto:jhierro at tid.es>
To:     fiware-wpl at lists.fi-ware.eu<mailto:fiware-wpl at lists.fi-ware.eu> <fiware-wpl at lists.fi-ware.eu><mailto:fiware-wpl at lists.fi-ware.eu>, fiware-wpa at lists.fi-ware.eu<mailto:fiware-wpa at lists.fi-ware.eu> <fiware-wpa at lists.fi-ware.eu><mailto:fiware-wpa at lists.fi-ware.eu>


Dear colleagues,

  One of the actions that we need to carry out is the review of the contents of the FI-WARE Open Specifications.

  The date that the EC has given to us for re-submitting them is month 18, i.e., end of October.   Therefore, we should have enough time.   However, it is also true that FI-WARE Open Specifications are one of our key deliverables: they become the ultimate reference UC projects will rely on in order to develop apps based on our GEs.

   Please find the plan that I would like to follow to carry out a first review of the FI-WARE Open Specifications by end of August.  Additional reviews will follow but hopefully this first one will be able to deliver a new version of the specs that is robust and complete enough to be delivered to UC projects:


Chapter to be reviewed
        Reviewing chapter

Data
        Security

Cloud
        Data

Apps
        Cloud

IoT
        Apps

I2ND
        IoT

Security
        I2ND



  Leaders of reviewing chapters are asked to designate those members of their teams that own enough technical expertise to judge specifications from the perspective of usefulness by both an application developer (this particularly in the case of RESTFul APIs) and any party that aims to develop a GE implementation in compliance with FI-WARE Open Specifications.

  This first review should finish by end of this month, executing the following calendar:

  *   Reviewing chapter sends comments to leader of reviewed chapter with cc to fiware-wpl and fiware-wpa: August 27, 09:00am   (delivery of revisions to be checked in our follow-up confcall at 11:00am)
  *   Each chapters implement recommended changes: August 31st, 12:00pm CET


  Best regards,


-- Juanjo

-------------
Product Development and Innovation (PDI) - Telefonica Digital
website: www.tid.es<http://www.tid.es>
email: jhierro at tid.es<mailto:jhierro at tid.es>
twitter: twitter.com/JuanjoHierro

FI-WARE (European Future Internet Core Platform) Chief Architect

You can follow FI-WARE at:
  website:  http://www.fi-ware.eu
  facebook: http://www.facebook.com/pages/FI-WARE/251366491587242
  twitter:  http://twitter.com/FIware
  linkedIn: http://www.linkedin.com/groups/FIWARE-4239932





________________________________

Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at:
http://www.tid.es/ES/PAGINAS/disclaimer.aspx
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-wpa/attachments/20120827/ca3072b2/attachment.html>