[Fiware-wpa] GUIDELINES on how to publish Open Specifications

[Juanjo Hierro]

Dear colleagues,

  I have updated the guidelines defined in our private wiki on how to publish the FI-WARE Open Specifications.   You can still find them at:
https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Where_and_how_to_publish_Open_Specifications
  Please read the guidelines carefully.   We WON'T start applying them until tomorrow after I send an email giving you green flag.   This is to allow you to read the guidelines first, and raise any issue you may detect or formulate any doubt you may have.   I will check issues/doubts after lunch today and will come back with a resolution on any issues before the green flag tomorrow based on discussions over the mailing lists.   That way we will prevent that teams start publishing things before fixing any issue.

  Note that I have updated the template for RESTful API specifications in order to reflect the agreements after discussion of comments raised by the Security chapter.   Following is a summary of these changes:

  *   I have drop some standard/fixed contents of the "Intended Audience" section and moved them to the "How to read FI-WARE RESTful API Specifications" section on the single common page we have defined for common aspects in FI-WARE RESTful API specifications located at: https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Common_aspects_in_FI-WARE_Open_Restful_API_Specifications
  *   I have also refined the text of the "How to Read This Document" section so that it refers to the the common "How to read FI-WARE RESTful API Specifications" section described above
  *   I have moved the "Authentication" and the "Representation Transport" sections to the single common page we have defined for common aspects in FI-WARE RESTful API specifications
  *   I have simplified the "Representation format" section taken advantage that many of the details that were there can be moved to the single common page we have defined for common aspects in FI-WARE RESTful API specifications
  *   I have moved fixed contents of the "Limits" and "Extensions" sections to the single common page we have defined for common aspects in FI-WARE RESTful API specifications.  Then, you only need to specify the list of valid error and response codes, together with some examples of valid responses.

  Nevertheless, it is not absolutely mandatory to adapt to the proposed updated template now if you had already completed your API specification following the previous template.   However, the more, the better.  You can defer final adaptation to end of June.

  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/20120515/df5a5846/attachment.html>