Hi Daniel, Please find my comments between lines of your mail. I would also like to hear others' opinions. I haven't included the fiware-security mailing list in the discussion to limit the discussion. I guess that we should be able to reach an agreement among involving just the Working Package Architects (of course, they may consult things internally in their teams) We should close the discusion by tomorrow EOB at the latest. Best regards, -- Juanjo On 06/04/12 15:25, GIDOIN Daniel wrote: Dear Juanjo, Concerning the format of Open Specifications proposed, our firm position on this matter is that several important modifications are indispensables. We strongly advocate that these modifications will considerably ease the task of providing Open Specifications for future and current APIs. The idea behind the recommendations and additional guidelines included here, is to account for the feedback from the developers, as well as keep track of their point of view. Experience has shown that verbose APIs specifications tend to be considered as hardly accessible from the users of a given API, who therefore prefer to simply discard the given API. This does not underestimate the crucial role of the documentation and specs of an API, but more precisely formulate the need for concision and efficiency in such documents. Our recommendations are as follow: - "Intended audience" can be reduced to a concise description, maybe the provided example is not intended to be taken verbatim, but this is only to give a definitive version. My idea is to create a single wiki page from which all FI-WARE REST API specifications can be located. Something like a directory. I believe I had explained this but probably it's worth explaining it in the guidelines we had published (https://forge.fi-ware.eu/plugins/mediawiki/wiki/fi-ware-private/index.php/Where_and_how_to_publish_Open_Specifications) Assuming that "directory" wiki page is created, we may include there some sections like this one whose contents may be written as to work with all API specifications. -"API Change History" may in some cases be useful for developers that use versioning, but the common practice (and a simpler one) is to provide these changes, showing the evolution of the API, at a separate notice, so that informed users may consult it if so required. If you want to have this info "as a separate notice", let's just make this section a link to a dedicated wiki page where the history is shown. However, the history is necessary. It's not just about API versioning. You may realize at a given point in time, as an example, that you have to clarify some specific point about the behavior because there might be different interpretations. Then you update the specification, but you need to highlight you have made such update for the sake of programmers. It's good that you raise the comment about API versioning because we haven't addressed it and we need to be able to handle it. Maybe it is not an urgent issue right now but we need to think about it. Comments are welcome, otherwise we will come with a proposal (nevertheless, we can go without a solution on how to deal with versioning for the FI-WARE first release) - It is strongly recommended to define a unique set of instructions on "How to Read This Document" for all the APIs involved or developed in the project. This will be therefore located in a separate part of the repository containing all the APIs, so that redundancy, if not avoided, is at least kept at the lowest possible level. I would treat this section as the one on "Intended Audience". - The "Resources summary" as a diagram may be optional. We propose instead a simple listing in textual form of the nearest hierarchy, in the inheritance sense of the term. An example might be the beginning of each class' spec in the Java SDK. Let's allow using different forms including the one you suggested. It would be up to the editor to choose one. However, I guess we all agree this section is mandatory. "Authentication", and "Representation Format" are to be filled according to the requirements of a given API (which may eventually include none). As for "Representation Format", since the indicated text on the Wiki must be included, and apparently is not subject to change, there is no obvious need to include it in each particular API, but in a separate section common to all the APIs. Let's make this be part of the common page we were talking about before. It is our firm belief that some of the fields mentioned in the proposal are superfluous, and do not answer to a precise need (such as "Resource identification"). Other fields are intuitively used where necessary, so explicitly listing them in the general form proposal may be avoided, and the choice left to the editor of the Open spec him(her)self (for ex. the "Optional" sections). We are not sure about this. What may be "obvious" for you may not be "obvious" for some developers. The "Limits" section and subsections do not seem to offer a particular help in the task of informing users and the developers using the API. Maybe the advantage of having this should be provided? We think that a well-designed REST API should take into account the definition of the mentioned "limits". On one hand, if such limits are not present, APIs would be vulnerable to attacks (e.g., "denial of service" attacks). On the other hand, developers should take into account such limits when programming applications. If APIs defined in your chapter do not plan to incorporate this functionality in the implementation delivered for the first release, they should plan to implement them soon. As examples to follow during the writing process of Open Specifications, and of our previous suggestions, the reader can refer to the JAVA API Specification (available at http://docs.oracle.com/javase/6/docs/api/ ), another example being the API Specifications provided by the Apache Foundation (such as Mojo, available at http://maven.apache.org/developers/mojo-api-specification.html ). These are of course only illustrations of what we are convinced to be very good examples of good practices to follow when providing the Open Specs, but remain nevertheless the blueprints of what to be expected as a result for an Open Specification. It's not that easy to extrapolate from API specifications that correspond to Java APIs. We are trying to cover what would be needed to provide a complete specification of a REST API. The proposed template is inspired on well-known REST API specifications like the OpenStack API. Best regards, -- Juanjo Best regards Daniel ________________________________ 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/20120411/b559e6eb/attachment.html>
You can get more information about our cookies and privacy policies clicking on the following links: Privacy policy Cookies policy