Hi Xebaz, I share your thoughts. I'm not used to work with REST, but i think somebody enhancing and maintaining this part specifically is really a good thing.
Le 14/06/2016 à 01:26, Xebax a écrit : > Hi everyone, > > I've recently discovered the REST API of Dolibarr and as a developer > that will use this API (in a client app), I would like to suggest some > improvements. The benefits would be: > 1) to have an API that is closest to the commonly accepted practices > in the industry, thus an API easier to understand for the developers > that would like to use it > 2) to use the Restler API Explorer for the documentation; it's great > for browsing the API but also playing with it > (see https://github.com/Luracast/Restler-API-Explorer/) > 3) to let the Restler framework do more job, thus to write less code > in order to expose the same services > > The main drawback is that this requires to break the compatibility > with the current definition of the API, which is not compliant with > the common practices used in the industry. I say "common practices" > because I'm not a REST API expert and I can't give solid arguments to > defend my point. My suggestions are only based on the experience I > have in working with REST APIs, both in using them and in writing > them. I have learned from resources on the web like: > http://www.restapitutorial.com/lessons/restquicktips.html > > The biggest problem I see in the current API is in the definition of > the URLs used in the CRUD operations. For example, for the third > parties, the URL are: > get the list: GET /thirdparty/list?api_key=token > get the list filtered to keep only the customers: GET > /thirdparty/list/customers?api_key=token > get an object: GET /thirdparty/{id}?api_key=token > create an object: POST /thirdparty?api_key=token > modify an object: PUT /thirdparty/{id}?api_key=token > delete an object: DELETE /thirdparty/{id}?api_key=token > > A definition more compliant with the common practices would be: > get the list: GET /thirdparties/ > get the list filtered to keep only the customers: GET > /thirdparties/?type=customers > get an object: GET /thirdparties/{id} > create an object: POST /thirdparties/ > modify an object: PUT /thirdparties/{id} > delete an object: DELETE /thirdparties/{id} > and the api_key would be transferred in the headers. > > This breaks the compatibility with the current API but the REST API is > very recent in Dolibarr and I think it's not a problem do to that now > (I suppose that there is not a lot of people using it). > Moreover, this modified API would be very well documented by the > Restler API Explorer. See, for example, the Documentation example of > Restler: > http://restler3.luracast.com/examples/_008_documentation/explorer/index.html#!/authors/list_get > > I have started to modify the API locally. The good news are that there > is not a lot to do to make the improvements described above. For the > moment I have modified the API for contacts and users. Here is a > screenshot of the result in the Restler API Explorer: > https://framapic.org/Mtf47PSHLWIp/gHpsSllmakX6.png > > Note that the api_key must be provided to the Explorer in order to see > the API because it is protected. > > This is work in progress. Before continuing, I would like to have some > feedback from you, to know if you agree with my proposal and if it > deserves more work. I would also like to know if these modifications > could be integrated in the future version 4.0. > > After that, I plan to add members and subscriptions to the API because > I need them in the short term. > > Thanks for your feedback. > Best regards, > > > _______________________________________________ > Dolibarr-dev mailing list > [email protected] > https://lists.nongnu.org/mailman/listinfo/dolibarr-dev
_______________________________________________ Dolibarr-dev mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/dolibarr-dev
