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
address@hidden
https://lists.nongnu.org/mailman/listinfo/dolibarr-dev
