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, -- Xebax
signature.asc
Description: PGP signature
_______________________________________________ Dolibarr-dev mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/dolibarr-dev
