Open christianlupus opened 4 years ago
christianlupus
commented
4 years ago @dromer @baradhili I did not remove the needs-triage tag and added a Must Have tag as this seems a personal opinion about the importance of the feature request. If you are ok with it, please adopt the tags accordingly.
dromer
commented
4 years ago I am not familiar with OpenAPI specifically. Mostly general REST concepts (and most cases that I've had to build something it ended up needing a lot of customization, so lets say REST-like).
However, there is documentation on the API, it's just not very human readable. You can find it on /api/doc on any PK install.
Ie.: https://demo.partkeepr.org/api/apidoc
So the current API is built using Hydra - which by itself is very well defined. If you want to change the API this is of course completely breaking (which means large parts of the front-end need to be rewritten as well). I don't think this is a very realistic endeavor at this point.
If the problem is no good documentation isn't then the solution better documentation ?
In the case of having a well documented API I agree this is a Must have.
christianlupus
commented
4 years ago First of all, OpenAPI is a specification on APIs. So in fact, there is a multitude of tools available for different purposes.
You might get the basic idea of such a definition in this example which also represents an editor for such APIs. You see it is a mixture of documentation (with human-readable descriptions, error messages and the like) with development tools. You can e.g. generate API requests on the backend from the right side directly for testing.
I am aware that Hydra is somehow used for the current implementation. I am honest, I did not make myself comfortable with Hydra very well. Also, I think there is only the machine-readable format in JSON-LD at /api/apidoc at the moment. The human-friendly version is not working right now. I consider an easily maintainable (and fixed) documentation and reference/standard (of the API endpoints) essential for any sort of success.
Also, as #1007 states clearly, the hydra documentation is not complete. So there might be semantic additions that are not in the JSON-LD file. Thus it is (in my opinion) not sufficient, especially as reference
Yes, the foremost intention is to have better documentation of what data is to be expected on both sides of the transfer.
dromer
commented
4 years ago The only 'docs' I can find is: https://wiki.partkeepr.org/wiki/Developers/API
To be more specific, we currently use: https://packagist.org/packages/dunglas/api-bundle This package is deprecated and the only suggestion is to use: https://packagist.org/packages/api-platform/api-pack
api-platform states:
It contains a PHP library to create fully featured APIs supporting industry-leading standards (JSON-LD and Hydra, GraphQL, OpenAPI...)
So, either way the migration will potentially give us other options for API choices.
christianlupus
commented
4 years ago The thing I am intending here is to have a clear interface that serves as a separation of backend and frontend. The hydra definition is in the code. Thus changes in the interface can easily happen "by the way". When having a clear API specification that is separated from the main code base (can be placed in an adjacent folder) allows both checking the frontend and backend as well as manual API invocations. Just wanted to keep this intention documented as it seems not clear in hindsight for me.
Feature description
At the moment there is no good documentation regarding the API between the (server) backend and the (browser) frontend. We need something in order to allow for further development.
The software was mainly written by a single person in the past. With #1059 this is no longer true and we need to find a way to manage group-based development in the project. Clear documentation and formulated requirements (on the behavior of both the backend and the frontend) is the minimal prerequisite for the cooperation.
References
There are a set of open issues that are related but focus on different aspects of a working API documentation: #678 and #1007 are the most pressing. Other issues are mainly stuck because the assumptions in the interface are not clear.
Additional information
Personally, I favor a clear OpenAPI specification. As a side effect, we force ourselves to a clear interface that keeps compatible. A change in the API would cause a major release increment.