Hello !
It seems that you've done a great work !
I'll check it out as soon as I can.
Have a nice day,
Gilles Lengy Artaban Communication 33 (0)1 40 09 18 18 www.artaban.fr spip.artaban.fr Adhérent de l'April (www.april.org)
Le 24/06/2016 à 13:10, Xebax a écrit :
Hi everybody, I contacted jfefe as suggested by Raphaël. Here is a summary of our conversation. Jean-François, feel free to correct or add anything. The REST API has been modified in order to: 1) Have an API that is closest to the common practices in the industry. That also means: - easy understanding for the developers that would like to use it - better integration with other tools - better adoption 2) Use the Restler API Explorer for documenting the API. The Restler API Explorer (based on Swagger UI) generates a beautiful and easy to browse documentation. And above all, it allows playing with the API: that's a very effective way to discover the API and learn how to use it. Note: A comment in the PR says that the Restler API Explorer should be provided in a separate module. I don't understand that because the Restler API Explorer is bundled in the version of Restler that is currently included in Dolibarr. There is no extra dependency to install in order to have it. 3) Keep the compatibility with the existing API. The definition and implementation of the new API follow these rules: - each core object of Dolibarr (contact, invoice, ...) appears as a resource and the path to the resource is the name of the core object, in English and pluralized (contacts, invoices, ...) - the corresponding class has the same name and it is in a file named api_<classname>.class.php (class Contacts in api_contacts.class.php, class Invoices in api_invoices.class.php, ...); this naming is compatible with the existing/future naming in the core: the core classes are/will be named in English in singular (Contact, Invoice, ...), in files named <classname>.class.php - the CRUD operations are implemented using the default methods of Restler: index() the list of all objects get() to get one object post() to create an object put() to update an object delete() to delete an object see http://restler3.luracast.com/examples/_007_crud/readme.html for more details about that - routing: automatic routing is used ad much as possible and manual routing is used only when the automatic routing does not give the expected result; smart auto-routing is enabled to avoid having unnecessary routes (without smart auto-routing, a route is created for each optional parameter in a method) see http://restler3.luracast.com/examples/_006_routing/readme.html for more details about that A note about using the plural: This is not a personal choice or preference, this is a widely adopted practice. See for example: - http://www.restapitutorial.com/lessons/restquicktips.html - http://apigee.com/about/blog/technology/restful-api-design-plural-nouns-and-concrete-names - the Restler examples (again): http://restler3.luracast.com/examples/_007_crud/readme.html I admit that there is a debate and I have no unquestionable argument to maintain my point of view. Example of discussion: http://stackoverflow.com/questions/6845772/rest-uri-convention-singular-or-plural-name-of-resource-while-creating-it About the compatibility with the existing API: The existing API has been moved to files named api_deprecated_<classname>.class.php (class ContactApi moved from api_contact.class.php to api_deprecated_contact.class.php, ...). These classes are there only for backward compatibility and are marked as deprecated in their description. They should not be modified anymore and users should be encouraged to use the new API instead. I don't know what are the deprecation rules in Dolibarr. The support of the deprecated API should be removed according to these rules. The work that is already done has been submitted in this pull request: https://github.com/Dolibarr/dolibarr/pull/5379 and here is how the API looks like in the explorer: https://cloud.githubusercontent.com/assets/8964954/16260447/d1bdf19c-3867-11e6-95f2-4071750d6ba7.png Note: The "root" entry at the top is the one that contains the existing API, for backward compatibility. I think there is more to do to obtain a good API: - better response codes: * 201 instead of 200 when an object is created * always return an error when an operation fails (currently one can get 200 for a delete that fails for example) - consistent response bodies (again, we currently have different behaviors for the delete() methods) - better documentation - update the README - update the skeleton class (well, I am not a big fan of having a skeleton class because it encourages copy-pasting; factorizing some code could be another way to make implementing new classes easier) The wiki also should be updated, as jfefe told me. I have found this: https://wiki.dolibarr.org/index.php/Module_Web_Services but it is about the SOAP web services. Should we add info here about the REST API or create a new page? Moreover I would like to add Members and Subscriptions to the API because I need them very soon. Thank you all for your feedback and support. Have a good day.
_______________________________________________ Dolibarr-dev mailing list address@hidden https://lists.nongnu.org/mailman/listinfo/dolibarr-dev
| Garanti sans virus. www.avast.com |