OpenHMIS Progress Report

[Dan Schultz]

Hello all,

  I'm kicking off another round of updates to the OpenHMIS API.  One of my goals for this phase is to bring the API closer to having the same endpoint signatures as the HMIS Lynk implementation.

  To that end, I may throw out a few questions in the coming weeks, so keep an ear out!

  I have been working on building out exception handling.  I'm basing my exceptions as much as possible on the HMIS Lynk API implementation, specifically https://github.com/servinglynk/hmis-lynk-open-source/blob/master/hmis-clientapi/src/main/java/com/servinglynk/hmis/warehouse/rest/common/ExceptionMapper.java

  Eric: is there any documentation that outlines the expected structure of the exception objects themselves in the current HMIS API spec?

  I'm also going to want to improve the format of the actual return values of the OpenHMIS endpoints.  Right now the returned objects are based on HUD standards, but it would be good to make sure the two implementations align.

Best,

 - Dan

--

--
Dan Schultz
P: (215) 400-1233
E: schu...@media.mit.edu
T: @slifty
W: http://www.slifty.com

C: http://calendly.com/slifty

[Eric Jahn]

Dan,
Thanks for your hard work at converging the APIs.  This will help others see the value in joining us.  We'll do what we can to keep this rolling forward quickly.

As for the error objects, we have this format.  I'm checking if it aligns to any specific standard or convention:

{
  "errors": {
    "error": {
      "code": "ACCOUNT_ALREADY_EXISTS",
      "message": "An account with the specified username already exists. username: any...@hmisdomain.com"
    }
  }
}

-Eric

--
You received this message because you are subscribed to the Google Groups "hmis-api" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hmis-api+u...@googlegroups.com.
To post to this group, send email to hmis...@googlegroups.com.
Visit this group at https://groups.google.com/group/hmis-api.
To view this discussion on the web visit https://groups.google.com/d/msgid/hmis-api/CAAy%2BrnV6MR%2Boc%3DtBAzwxFDZ7uMQ7%3DFD%2BMU3QiSSc8dzPoU-JKQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Eric Jahn]

Dan, 

Just to follow up on this, I think we are going to add this to the sample error response examples in our api raml code.  Aside from that, I don't think we have any docs on the subject yet.  I think HMISLynk's looks similar to the "Google JSON style guide" I saw posted here: https://google.github.io/styleguide/jsoncstyleguide.xml#error  .  -Eric

[Dan Schultz]

This is great Eric,

  The HMIS structure you are porposing here is very similar to the Google style guide but there are a few differences that I think we should consider adapting around.

  Specifically, the "errors" and "error" fields are swapped, and the "errors" field is not an array in your version but probably should be.

  If we want to keep the current HMIS style, I would recommend shifting the format to be more like this:

{
  "errors": [

      "code": "ACCOUNT_ALREADY_EXISTS",
      "message": "An account with the specified username already exists. username: any...@hmisdomain.com"

   ]
}

Having errors be an object that contains only one field (error) means that you will never be able to return more than one error (making the "errors" label misleading).  I suspect the current JSON structure is a translation from an originally XML based structure, which would totally appropriately have <errors><error></error></errors> -- in JSON since lists are done in the form of arrays it is implied that each item in an array labeled "errors" is an error.

All that said, I like the Google style even more since it is apparently a proposed standard, but it also implies that there is only ever going to be a single "type" of error (grounded as HTTP status codes) with several sub-errors where appropriate (thus making error handling on the client side more direct since there is no question about what the primary error that needs to be handled is.)

What do you think of making one of these tweaks?  The first option being the above "errors" with no "error" field, the second being something like what google does:

{

   "error": {
    "code": HTTP_ERROR_GOES_HERE,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
  }

}

Best,

 - Dan

[Eric Jahn]

Yes, I definitely like the ability to send many errors, especially if we are already using that terminology.  There are other "standards" out there, so I'm hoping we can peg it once to the best spec/standard and make the changes as the standard changes, instead of doing to an interim solution based on existing work and then changing wholesale to an existing spec later.

Does anybody on this list have any JSON API recommendations we should follow?

I was checking out the ones mentioned here: http://stackoverflow.com/questions/12806386/standard-json-api-response-format and buried in that discussion, I saw this: https://datatracker.ietf.org/doc/rfc7807 .  It might have technical merits, but I've yet to drink the Kool-Aid, since it seems quite different from what I'm used to seeing.  But I love the process around maintaining it.  My .02, I also like the Google Style Guide best so far.  I also how it has the API version in the error object.  

Should we just adhere to Google's Style Guide, and hope it stays mainstream/accepted (question directed at whole listserv)?  I don't have strong opinions on this; I just want something that works, is considered a mainstream methodology, and has some sort of SDO process around it, if possible.  -Eric

[Eric Jahn]

Another update: our Coordinated Entry folks are all using Spring Boot's built-in HTTP response conventions.  So I'll have to look all the formats in use by that.  I'm sure we can override to our common API needs though.