My GSoC Issues for the Summer


Today I thought of giving a brief overview on some of my issues and how I’ve been tackling them. I’ll try describe each issue in simple terms and workarounds we’ve taken to solve them.

RESTWS-560Create API Overview Docs

The issue suggests that we add an overview (ie: description) to the existing swagger documentation (swagger-ui) explaining users about the OpenMRS API concepts such as the resource representations, authentication and the like. However the idea behind swagger-ui I believe is to make any API self explanatory, so no more guidance should be needed for the user. So my suggestion was to simply upgrade the swagger-ui which my mentors also agree.

RESTWS-568Optimize Swagger Spec Creation

Optimize here in the sense refers to caching. Swagger Spec of OpenMRS is generated pragmatically at runtime and is accessible under: /openmrs/module/webservices/rest/swagger.json

The uri is mapped to a spring handler. So every time a web request is made to that url the handler method is invoked which returns the result as a String. The problem is that the result never is cached. So for every request it will repeat the process of regenerating the spec which is quite an expensive operation.

There’s no possibility that the spec would change unless the server context is refreshed. So why not just cache it once every context refresh instead of repeating an costly operation, and reuse the result from the last time!

RESTWS-562Improve Resource Definition Documentation

In the old swagger spec almost all the properties are documented as string. But as you may know Swagger supports many different data types than just strings.

// old spec
"DrugGet": {
  "properties": {
    "uri": {
      "type": "string"
    },
    "uuid": {
      "type": "string"
    },
    "minimumDailyDose": {
      "type": "string"
    },
    "combination": {
      "type": "string"
    },
    "concept": {
      "type": "string"
    }..

A property can be of type, integer, boolean, number etc. These types can also take several formats. So for example string can be in the format such as url, password, enum. A property can also point to a reference ($ref) object.

A PR is being submitted and is currently under review. This I consider one of my mighty PRs with substantial code changes. With the new changes the improved definition would look something as follows, but with more finely define data types. The new spec also include more than just the default representation of a resource.

// new spec
"DrugGet": {
  "properties": {
    "uri": {
      "type": "string",
      "format": "uri"
    },
    "uuid": {
      "type": "string"
    },
    "minimumDailyDose": {
      "type": "number",
      "format": "double"
    },
    "combination": {
      "type": "boolean",
      "default": false
    },
    "concept": {
     "$ref": "#/definitions/ConceptGetRef"
    }..

There remains more issues, but they to me sounds quite technical, so would better not put in simple context.

 

Leave a comment

Your email address will not be published. Required fields are marked *