API convergence questions: objects and ids

[Cecilia Donnelly]

Hi Eric and everyone,

I hope you all had a great weekend.  I have a couple questions about the current state of the HMIS API, for convergence efforts with the OpenHMIS API:

1) Would you mind pointing me to some information about the objects that the HMIS API returns right now?  I poked around a bit but couldn't find those values.

2) We've added generic id fields to the OpenHMIS API (e.g. "id" instead of "clientID").  Part of the reason I was asking about your objects in (1) is to find out how you're currently handling ids.  I think you have type-specific ids -- is that right?  How did you make that decision?  We added generic ids in part so that we store the type in just one place, the table name, instead of both table and field names.  We'd rather have our behavior line up with yours, of course, so I'd appreciate hearing how you're currently handling it and why.

Thanks!
Cecilia

--

Cecilia Donnelly

Open Source Specialist

312-757-5411

cdon...@opentechstrategies.com

[Eric Jahn]

Cecilia, 

Yes, a nice weekend it was, and I hope yours was the same!  The AnyPoint site should provide example objects and the payload format specification (JSON Schema) for 200 code responses and requests, but the full error responses (400s) need to be standardized and posted, as Dan pointed out earlier, and for which we made this issue.  I just made this related one to get the documentation up to snuff as well. I looked at /v2015/clients/{client_id} GET on the 2015 API portal page (and I see now that 2015 is not all posted yet), and it had those items in the definition on the portal, except for the error objects. Could you give me a specific endpoint that you are looking at that is missing the info?

For your second question, the directive was to use HUD's ID names if they assigned any.  For clients, HUD assigned PersonalID.  We should have used that clients.personalID, but I think the developer working on this preferred the consistency with the collection name of client.clientID instead.  But yes, we could have just used client.id instead of client.clientID.  Likewise, we used enrollment.enrollmentID instead of HUD's enrollment.projectEntryID.  So there are three ways we could have gone.  I think aligning closely with HUD's names would be the way to go, as opposed to how we did it, or just using x.id.  And then if we think it's too redundant, work with HUD to make it x.id.  What do you think?  -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/CACfdBSDgaCqahi8Pjcu1f9tXO7MkXAXXnrKtUcQ8zO6LCusv1Q%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Cecilia Donnelly]

Hey Eric,
I see the API documentation now and it's very helpful.  Thank you!  Could we add a link to that page from the README file in either the docs repo or the main code repo, or both?  I'm happy to put in a PR for that if it would be useful.

More soon,
Cecilia

[Eric Jahn]

Cecilia, sure can!  Karl, I like the x.id convention also, and we can move to that.  In our reporting schema (which is a different schemafor us), we'll have to convert x.id to x.PersonalID so HMIS SMEs can relate it to the data standard element 1:1.  Of course HUD doesn't say anything about how to name API methods or database schema, but we will need to accommodate their names in reporting tools/dictionaries, and such, so using x.id will cause an additional layer of abstraction.  But yes, happy to go there, in order to make the HMIS API look more conventional.  Feel free to submit an issue for this.  Eric