There was a project to document the Web Services API end-points in a GitHub repository, however that needs to be manually updated.
I wanted to suggest using StopLight (https://stoplight.io/) to aid this process and ensure the ability to setup a mock server and actually test the end-points inbuilt.
The content is actually stored in an OpenAPI based format, and can be extended to FHIR mappings too
Thoughts are welcome
It would be very good to improve and keep the endpoint documentation up to date. I think myself and other frontend developers feel a daily friction of trying to figure out what endpoints are available to be used, the correct format, which parameters are supported, and what the expected response values can look like. I agree with @ssmusoke that an automated tool can help in some of those situations. Personally I have been very happy with Swagger both as a frontend consumer and as a backend dev documenting my endpoints. That tool has the added bonus of being able to submit real requests to try out endpoints if configured correctly.
Currently it seems like some documentation is available on rest.openmrs.org, although other endpoints which are now a part of the reference application on dev3 (like the cohort module) do not have their documentation included there, but instead separately in the module README. So for this I think there is some documentation there, it’s just scattered across multiple sites.
Would the community support centralizing some of these resources?
rest.openmrs.org was supposed to be the centralised point for documenting the REST API, but we haven’t necessarily done a good job of keeping it up-to-date. Contributions to that page can be made here: GitHub - openmrs/openmrs-contrib-rest-api-docs: OpenMRS REST API documentation. One problem with this set of API docs is it’s entirely unclear what it’s scope should be. I.e., is it just documentation of the default REST endpoints (i.e., those from the webservices.rest module)? Is it documentation of all the REST endpoints in the RefApp? Is it documentation for the platform REST endpoints? Those are three different, but overlapping, sets of endpoints and, as we’ve added modules into the RefApp 3.x, we clearly haven’t made the effort to add docs to that site.
Each instance of OpenMRS that has the REST module will have an automatically generated Swagger page like this. This generally will have at least an entry for all endpoints registered using the REST framework. Unfortunately, the documentation quality itself is kind of poor, which was the rationale for the rest.openmrs.org site in the first place.
@grace Having solid docs for the REST API is a very important consideration for DevX, especially with O3. I don’t know if there’s a way we can strategise to try and make this documentation better and part of the usual effore.
@ibacher It’s like you read my mind! While it was great having a dedicated technical writer working on the REST API documentation through Google Season of Docs 2019, that effort ended with the end of GSoD2019. This could be so much more sustainable if we can work documentation into our process and share the responsibility.